diff options
author | David Vrabel <david.vrabel@csr.com> | 2008-10-20 11:07:19 -0400 |
---|---|---|
committer | David Vrabel <david.vrabel@csr.com> | 2008-10-20 11:07:19 -0400 |
commit | 61e0e79ee3c609eb34edf2fe023708cba6a79b1f (patch) | |
tree | 663deacffd4071120dc9badb70428fe5f124c7b9 /Documentation | |
parent | c15895ef30c2c03e99802951787183039a349d32 (diff) | |
parent | 0cfd81031a26717fe14380d18275f8e217571615 (diff) |
Merge branch 'master' into for-upstream
Conflicts:
Documentation/ABI/testing/sysfs-bus-usb
drivers/Makefile
Diffstat (limited to 'Documentation')
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. |
22 | CodingStyle | 22 | CodingStyle |
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. |
24 | development-process/ | ||
25 | - An extended tutorial on how to work with the kernel development | ||
26 | process. | ||
24 | DMA-API.txt | 27 | DMA-API.txt |
25 | - DMA API, pci_ API & extensions for non-consistent memory machines. | 28 | - DMA API, pci_ API & extensions for non-consistent memory machines. |
26 | DMA-ISA-LPC.txt | 29 | DMA-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. |
160 | highuid.txt | 163 | highuid.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. |
162 | hpet.txt | ||
163 | - High Precision Event Timer Driver for Linux. | ||
164 | timers/ | 165 | timers/ |
165 | - info on the timer related topics | 166 | - info on the timer related topics |
166 | hw_random.txt | 167 | hw_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. |
252 | moxa-smartio | 253 | moxa-smartio |
253 | - file with info on installing/using Moxa multiport serial driver. | 254 | - file with info on installing/using Moxa multiport serial driver. |
254 | mtrr.txt | ||
255 | - how to use PPro Memory Type Range Registers to increase performance. | ||
256 | mutex-design.txt | 255 | mutex-design.txt |
257 | - info on the generic mutex subsystem. | 256 | - info on the generic mutex subsystem. |
258 | namespaces/ | 257 | namespaces/ |
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 @@ | |||
1 | What: /sys/bus/usb/drivers/usbtmc/devices/*/interface_capabilities | ||
2 | What: /sys/bus/usb/drivers/usbtmc/devices/*/device_capabilities | ||
3 | Date: August 2008 | ||
4 | Contact: Greg Kroah-Hartman <gregkh@suse.de> | ||
5 | Description: | ||
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 | |||
15 | What: /sys/bus/usb/drivers/usbtmc/devices/*/usb488_interface_capabilities | ||
16 | What: /sys/bus/usb/drivers/usbtmc/devices/*/usb488_device_capabilities | ||
17 | Date: August 2008 | ||
18 | Contact: Greg Kroah-Hartman <gregkh@suse.de> | ||
19 | Description: | ||
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 | |||
30 | What: /sys/bus/usb/drivers/usbtmc/devices/*/TermChar | ||
31 | Date: August 2008 | ||
32 | Contact: Greg Kroah-Hartman <gregkh@suse.de> | ||
33 | Description: | ||
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 | |||
43 | What: /sys/bus/usb/drivers/usbtmc/devices/*/TermCharEnabled | ||
44 | Date: August 2008 | ||
45 | Contact: Greg Kroah-Hartman <gregkh@suse.de> | ||
46 | Description: | ||
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 | |||
54 | What: /sys/bus/usb/drivers/usbtmc/devices/*/auto_abort | ||
55 | Date: August 2008 | ||
56 | Contact: Greg Kroah-Hartman <gregkh@suse.de> | ||
57 | Description: | ||
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 | ||
89 | What: /sys/bus/usb/device/<busnum>-<devnum>...:<config num>-<interface num>/supports_autosuspend | ||
90 | Date: January 2008 | ||
91 | KernelVersion: 2.6.27 | ||
92 | Contact: Sarah Sharp <sarah.a.sharp@intel.com> | ||
93 | Description: | ||
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. | ||
101 | Users: | ||
102 | USB PM tool | ||
103 | git://git.moblin.org/users/sarah/usb-pm-tool/ | ||
104 | |||
89 | What: /sys/bus/usb/device/.../authorized | 105 | What: /sys/bus/usb/device/.../authorized |
90 | Date: July 2008 | 106 | Date: July 2008 |
91 | KernelVersion: 2.6.26 | 107 | KernelVersion: 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 @@ | |||
1 | Where: /sys/bus/usb/.../powered | ||
2 | Date: August 2008 | ||
3 | Kernel Version: 2.6.26 | ||
4 | Contact: Harrison Metzger <harrisonmetz@gmail.com> | ||
5 | Description: Controls whether the device's display will powered. | ||
6 | A value of 0 is off and a non-zero value is on. | ||
7 | |||
8 | Where: /sys/bus/usb/.../mode_msb | ||
9 | Where: /sys/bus/usb/.../mode_lsb | ||
10 | Date: August 2008 | ||
11 | Kernel Version: 2.6.26 | ||
12 | Contact: Harrison Metzger <harrisonmetz@gmail.com> | ||
13 | Description: 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 | |||
19 | Where: /sys/bus/usb/.../textmode | ||
20 | Date: August 2008 | ||
21 | Kernel Version: 2.6.26 | ||
22 | Contact: Harrison Metzger <harrisonmetz@gmail.com> | ||
23 | Description: 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 | |||
28 | Where: /sys/bus/usb/.../text | ||
29 | Date: August 2008 | ||
30 | Kernel Version: 2.6.26 | ||
31 | Contact: Harrison Metzger <harrisonmetz@gmail.com> | ||
32 | Description: The text (or data) for the device to display | ||
33 | |||
34 | Where: /sys/bus/usb/.../decimals | ||
35 | Date: August 2008 | ||
36 | Kernel Version: 2.6.26 | ||
37 | Contact: Harrison Metzger <harrisonmetz@gmail.com> | ||
38 | Description: 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 @@ | |||
1 | What: /sys/class/regulator/.../state | 1 | What: /sys/class/regulator/.../state |
2 | Date: April 2008 | 2 | Date: April 2008 |
3 | KernelVersion: 2.6.26 | 3 | KernelVersion: 2.6.26 |
4 | Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> | 4 | Contact: Liam Girdwood <lrg@slimlogic.co.uk> |
5 | Description: | 5 | Description: |
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: | |||
27 | What: /sys/class/regulator/.../type | 27 | What: /sys/class/regulator/.../type |
28 | Date: April 2008 | 28 | Date: April 2008 |
29 | KernelVersion: 2.6.26 | 29 | KernelVersion: 2.6.26 |
30 | Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> | 30 | Contact: Liam Girdwood <lrg@slimlogic.co.uk> |
31 | Description: | 31 | Description: |
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: | |||
51 | What: /sys/class/regulator/.../microvolts | 51 | What: /sys/class/regulator/.../microvolts |
52 | Date: April 2008 | 52 | Date: April 2008 |
53 | KernelVersion: 2.6.26 | 53 | KernelVersion: 2.6.26 |
54 | Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> | 54 | Contact: Liam Girdwood <lrg@slimlogic.co.uk> |
55 | Description: | 55 | Description: |
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: | |||
65 | What: /sys/class/regulator/.../microamps | 65 | What: /sys/class/regulator/.../microamps |
66 | Date: April 2008 | 66 | Date: April 2008 |
67 | KernelVersion: 2.6.26 | 67 | KernelVersion: 2.6.26 |
68 | Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> | 68 | Contact: Liam Girdwood <lrg@slimlogic.co.uk> |
69 | Description: | 69 | Description: |
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: | |||
79 | What: /sys/class/regulator/.../opmode | 79 | What: /sys/class/regulator/.../opmode |
80 | Date: April 2008 | 80 | Date: April 2008 |
81 | KernelVersion: 2.6.26 | 81 | KernelVersion: 2.6.26 |
82 | Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> | 82 | Contact: Liam Girdwood <lrg@slimlogic.co.uk> |
83 | Description: | 83 | Description: |
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: | |||
102 | What: /sys/class/regulator/.../min_microvolts | 102 | What: /sys/class/regulator/.../min_microvolts |
103 | Date: April 2008 | 103 | Date: April 2008 |
104 | KernelVersion: 2.6.26 | 104 | KernelVersion: 2.6.26 |
105 | Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> | 105 | Contact: Liam Girdwood <lrg@slimlogic.co.uk> |
106 | Description: | 106 | Description: |
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: | |||
116 | What: /sys/class/regulator/.../max_microvolts | 116 | What: /sys/class/regulator/.../max_microvolts |
117 | Date: April 2008 | 117 | Date: April 2008 |
118 | KernelVersion: 2.6.26 | 118 | KernelVersion: 2.6.26 |
119 | Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> | 119 | Contact: Liam Girdwood <lrg@slimlogic.co.uk> |
120 | Description: | 120 | Description: |
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: | |||
130 | What: /sys/class/regulator/.../min_microamps | 130 | What: /sys/class/regulator/.../min_microamps |
131 | Date: April 2008 | 131 | Date: April 2008 |
132 | KernelVersion: 2.6.26 | 132 | KernelVersion: 2.6.26 |
133 | Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> | 133 | Contact: Liam Girdwood <lrg@slimlogic.co.uk> |
134 | Description: | 134 | Description: |
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: | |||
145 | What: /sys/class/regulator/.../max_microamps | 145 | What: /sys/class/regulator/.../max_microamps |
146 | Date: April 2008 | 146 | Date: April 2008 |
147 | KernelVersion: 2.6.26 | 147 | KernelVersion: 2.6.26 |
148 | Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> | 148 | Contact: Liam Girdwood <lrg@slimlogic.co.uk> |
149 | Description: | 149 | Description: |
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 | ||
160 | What: /sys/class/regulator/.../name | ||
161 | Date: October 2008 | ||
162 | KernelVersion: 2.6.28 | ||
163 | Contact: Liam Girdwood <lrg@slimlogic.co.uk> | ||
164 | Description: | ||
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 | |||
160 | What: /sys/class/regulator/.../num_users | 173 | What: /sys/class/regulator/.../num_users |
161 | Date: April 2008 | 174 | Date: April 2008 |
162 | KernelVersion: 2.6.26 | 175 | KernelVersion: 2.6.26 |
163 | Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> | 176 | Contact: Liam Girdwood <lrg@slimlogic.co.uk> |
164 | Description: | 177 | Description: |
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: | |||
170 | What: /sys/class/regulator/.../requested_microamps | 183 | What: /sys/class/regulator/.../requested_microamps |
171 | Date: April 2008 | 184 | Date: April 2008 |
172 | KernelVersion: 2.6.26 | 185 | KernelVersion: 2.6.26 |
173 | Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> | 186 | Contact: Liam Girdwood <lrg@slimlogic.co.uk> |
174 | Description: | 187 | Description: |
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: | |||
181 | What: /sys/class/regulator/.../parent | 194 | What: /sys/class/regulator/.../parent |
182 | Date: April 2008 | 195 | Date: April 2008 |
183 | KernelVersion: 2.6.26 | 196 | KernelVersion: 2.6.26 |
184 | Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> | 197 | Contact: Liam Girdwood <lrg@slimlogic.co.uk> |
185 | Description: | 198 | Description: |
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: | |||
189 | What: /sys/class/regulator/.../suspend_mem_microvolts | 202 | What: /sys/class/regulator/.../suspend_mem_microvolts |
190 | Date: May 2008 | 203 | Date: May 2008 |
191 | KernelVersion: 2.6.26 | 204 | KernelVersion: 2.6.26 |
192 | Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> | 205 | Contact: Liam Girdwood <lrg@slimlogic.co.uk> |
193 | Description: | 206 | Description: |
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: | |||
203 | What: /sys/class/regulator/.../suspend_disk_microvolts | 216 | What: /sys/class/regulator/.../suspend_disk_microvolts |
204 | Date: May 2008 | 217 | Date: May 2008 |
205 | KernelVersion: 2.6.26 | 218 | KernelVersion: 2.6.26 |
206 | Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> | 219 | Contact: Liam Girdwood <lrg@slimlogic.co.uk> |
207 | Description: | 220 | Description: |
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: | |||
217 | What: /sys/class/regulator/.../suspend_standby_microvolts | 230 | What: /sys/class/regulator/.../suspend_standby_microvolts |
218 | Date: May 2008 | 231 | Date: May 2008 |
219 | KernelVersion: 2.6.26 | 232 | KernelVersion: 2.6.26 |
220 | Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> | 233 | Contact: Liam Girdwood <lrg@slimlogic.co.uk> |
221 | Description: | 234 | Description: |
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: | |||
231 | What: /sys/class/regulator/.../suspend_mem_mode | 244 | What: /sys/class/regulator/.../suspend_mem_mode |
232 | Date: May 2008 | 245 | Date: May 2008 |
233 | KernelVersion: 2.6.26 | 246 | KernelVersion: 2.6.26 |
234 | Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> | 247 | Contact: Liam Girdwood <lrg@slimlogic.co.uk> |
235 | Description: | 248 | Description: |
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: | |||
245 | What: /sys/class/regulator/.../suspend_disk_mode | 258 | What: /sys/class/regulator/.../suspend_disk_mode |
246 | Date: May 2008 | 259 | Date: May 2008 |
247 | KernelVersion: 2.6.26 | 260 | KernelVersion: 2.6.26 |
248 | Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> | 261 | Contact: Liam Girdwood <lrg@slimlogic.co.uk> |
249 | Description: | 262 | Description: |
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: | |||
258 | What: /sys/class/regulator/.../suspend_standby_mode | 271 | What: /sys/class/regulator/.../suspend_standby_mode |
259 | Date: May 2008 | 272 | Date: May 2008 |
260 | KernelVersion: 2.6.26 | 273 | KernelVersion: 2.6.26 |
261 | Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> | 274 | Contact: Liam Girdwood <lrg@slimlogic.co.uk> |
262 | Description: | 275 | Description: |
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: | |||
272 | What: /sys/class/regulator/.../suspend_mem_state | 285 | What: /sys/class/regulator/.../suspend_mem_state |
273 | Date: May 2008 | 286 | Date: May 2008 |
274 | KernelVersion: 2.6.26 | 287 | KernelVersion: 2.6.26 |
275 | Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> | 288 | Contact: Liam Girdwood <lrg@slimlogic.co.uk> |
276 | Description: | 289 | Description: |
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: | |||
287 | What: /sys/class/regulator/.../suspend_disk_state | 300 | What: /sys/class/regulator/.../suspend_disk_state |
288 | Date: May 2008 | 301 | Date: May 2008 |
289 | KernelVersion: 2.6.26 | 302 | KernelVersion: 2.6.26 |
290 | Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> | 303 | Contact: Liam Girdwood <lrg@slimlogic.co.uk> |
291 | Description: | 304 | Description: |
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: | |||
302 | What: /sys/class/regulator/.../suspend_standby_state | 315 | What: /sys/class/regulator/.../suspend_standby_state |
303 | Date: May 2008 | 316 | Date: May 2008 |
304 | KernelVersion: 2.6.26 | 317 | KernelVersion: 2.6.26 |
305 | Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> | 318 | Contact: Liam Girdwood <lrg@slimlogic.co.uk> |
306 | Description: | 319 | Description: |
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 @@ | |||
1 | What: /sys/kernel/profile | ||
2 | Date: September 2008 | ||
3 | Contact: Dave Hansen <dave@linux.vnet.ibm.com> | ||
4 | Description: | ||
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 | ||
9 | DOCBOOKS := wanbook.xml z8530book.xml mcabook.xml videobook.xml \ | 9 | DOCBOOKS := 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 | |||
95 | static 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 | |||
139 | static int io = 0x320; | ||
140 | |||
141 | int __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(&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 | |||
222 | static int users = 0; | ||
223 | |||
224 | static 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 | |||
241 | static 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 | |||
268 | static 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, &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(&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(&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(&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 | |||
493 | static unsigned long current_freq; | ||
494 | |||
495 | |||
496 | |||
497 | case VIDIOCGFREQ: | ||
498 | if(copy_to_user(arg, &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, &freq, | ||
516 | sizeof(unsigned long))!=0) | ||
517 | return -EFAULT; | ||
518 | if(hardware_set_freq(freq)<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 | |||
544 | static int current_volume=0; | ||
545 | |||
546 | case VIDIOCGAUDIO: | ||
547 | { | ||
548 | struct video_audio v; | ||
549 | if(copy_from_user(&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. &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(&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(&v, arg, sizeof(v))) | ||
676 | return -EFAULT; | ||
677 | if(v.audio) | ||
678 | return -EINVAL; | ||
679 | current_volume = v/16384; | ||
680 | if(v.flags&VIDEO_AUDIO_MUTE) | ||
681 | hardware_set_volume(0); | ||
682 | else | ||
683 | hardware_set_volume(current_volume); | ||
684 | current_muted = v.flags & | ||
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 | |||
722 | static int io = 0x300; | ||
723 | |||
724 | #else | ||
725 | |||
726 | static int io = -1; | ||
727 | |||
728 | #endif | ||
729 | |||
730 | MODULE_AUTHOR("Alan Cox"); | ||
731 | MODULE_DESCRIPTION("A driver for an imaginary radio card."); | ||
732 | module_param(io, int, 0444); | ||
733 | MODULE_PARM_DESC(io, "I/O address of the card."); | ||
734 | |||
735 | static 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 | |||
746 | static void __exit cleanup(void) | ||
747 | { | ||
748 | video_unregister_device(&my_radio); | ||
749 | release_region(io, MY_IO_SIZE); | ||
750 | } | ||
751 | |||
752 | module_init(init); | ||
753 | module_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> | ||
834 | static 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 | |||
910 | static int io = 0x320; | ||
911 | static int irq = 11; | ||
912 | |||
913 | int __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(&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 | |||
941 | static int users = 0; | ||
942 | |||
943 | static 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)<0) | ||
948 | return -EBUSY; | ||
949 | users++; | ||
950 | return 0; | ||
951 | } | ||
952 | |||
953 | |||
954 | static 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 | |||
982 | static struct wait_queue *capture_wait; | ||
983 | static int capture_ready = 0; | ||
984 | |||
985 | static void camera_irq(int irq, void *dev_id, | ||
986 | struct pt_regs *regs) | ||
987 | { | ||
988 | capture_ready=1; | ||
989 | wake_up_interruptible(&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 | |||
1007 | static int camera_poll(struct video_device *dev, | ||
1008 | struct file *file, struct poll_table *wait) | ||
1009 | { | ||
1010 | poll_wait(file, &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 | |||
1028 | static 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(&capture_wait, &wait); | ||
1037 | |||
1038 | while(!capture_ready) | ||
1039 | { | ||
1040 | if(file->flags&O_NDELAY) | ||
1041 | { | ||
1042 | remove_wait_queue(&capture_wait, &wait); | ||
1043 | current->state = TASK_RUNNING; | ||
1044 | return -EWOULDBLOCK; | ||
1045 | } | ||
1046 | if(signal_pending(current)) | ||
1047 | { | ||
1048 | remove_wait_queue(&capture_wait, &wait); | ||
1049 | current->state = TASK_RUNNING; | ||
1050 | return -ERESTARTSYS; | ||
1051 | } | ||
1052 | schedule(); | ||
1053 | current->state = TASK_INTERRUPTIBLE; | ||
1054 | } | ||
1055 | remove_wait_queue(&capture_wait, &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<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 | |||
1127 | static 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, &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(&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(&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(&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(&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(&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 | |||
1401 | static struct video_buffer capture_fb; | ||
1402 | |||
1403 | case VIDIOCGFBUF: | ||
1404 | { | ||
1405 | if(copy_to_user(arg, &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(&v, arg, sizeof(v))) | ||
1428 | return -EFAULT; | ||
1429 | if(v.width!=320 && v.width!=640) | ||
1430 | return -EINVAL; | ||
1431 | if(v.height!=200 && v.height!=240 | ||
1432 | && v.height!=400 | ||
1433 | && v.height !=480) | ||
1434 | return -EINVAL; | ||
1435 | memcpy(&capture_fb, &v, sizeof(v)); | ||
1436 | hardware_set_fb(&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, &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(&v, arg, sizeof(v))) | ||
1545 | return -EFAULT; | ||
1546 | if(v.width > 640 || v.height > 480) | ||
1547 | return -EINVAL; | ||
1548 | if(v.width < 16 || v.height < 16) | ||
1549 | return -EINVAL; | ||
1550 | hardware_set_key(v.chromakey); | ||
1551 | hardware_set_window(v); | ||
1552 | memcpy(&capture_win, &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: | |||
620 | For more details on what this should all look like, please see the | 620 | For more details on what this should all look like, please see the |
621 | ChangeLog section of the document: | 621 | ChangeLog 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 | ||
212 | 9. All RCU list-traversal primitives, which include | 212 | 9. 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 | ||
31 | If this list/array is made lock free using RCU as in changing the | 31 | If this list/array is made lock free using RCU as in changing the |
32 | write_lock() in add() and delete() to spin_lock and changing read_lock | 32 | write_lock() in add() and delete() to spin_lock() and changing read_lock() |
33 | in search_and_reference to rcu_read_lock(), the atomic_get in | 33 | in search_and_reference() to rcu_read_lock(), the atomic_inc() in |
34 | search_and_reference could potentially hold reference to an element which | 34 | search_and_reference() could potentially hold reference to an element which |
35 | has already been deleted from the list/array. Use atomic_inc_not_zero() | 35 | has already been deleted from the list/array. Use atomic_inc_not_zero() |
36 | in this scenario as follows: | 36 | in 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 | } } |
50 | 3. 4. | 50 | 3. 4. |
51 | release_referenced() delete() | 51 | release_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 @@ | |||
1 | Linux 2.4.2 Secure Attention Key (SAK) handling | 1 | Linux 2.4.2 Secure Attention Key (SAK) handling |
2 | 18 March 2001, Andrew Morton <akpm@osdl.org> | 2 | 18 March 2001, Andrew Morton |
3 | 3 | ||
4 | An operating system's Secure Attention Key is a security tool which is | 4 | An operating system's Secure Attention Key is a security tool which is |
5 | provided as protection against trojan password capturing programs. It | 5 | provided 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 @@ | |||
1 | If you want to use SELinux, chances are you will want | ||
2 | to use the distro-provided policies, or install the | ||
3 | latest reference policy release from | ||
4 | http://oss.tresys.com/projects/refpolicy | ||
5 | |||
6 | However, if you want to install a dummy policy for | ||
7 | testing, you can do using 'mdp' provided under | ||
8 | scripts/selinux. Note that this requires the selinux | ||
9 | userspace to be installed - in particular you will | ||
10 | need checkpolicy to compile a kernel, and setfiles and | ||
11 | fixfiles 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 | |||
23 | Step 4 will create a new dummy policy valid for your | ||
24 | kernel, with a single selinux user, role, and type. | ||
25 | It will compile the policy, will set your SELINUXTYPE to | ||
26 | dummy in /etc/selinux/config, install the compiled policy | ||
27 | as '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. | |||
85 | 23: Tested after it has been merged into the -mm patchset to make sure | 85 | 23: 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 | |||
89 | 24: 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: | |||
41 | Linux 2.6: | 41 | Linux 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 | ||
46 | What Criteria Determine Acceptance | 46 | What 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: | |||
77 | http://savannah.nongnu.org/projects/quilt | 77 | http://savannah.nongnu.org/projects/quilt |
78 | 78 | ||
79 | Andrew Morton's patch scripts: | 79 | Andrew Morton's patch scripts: |
80 | http://www.zip.com.au/~akpm/linux/patches/ | 80 | http://userweb.kernel.org/~akpm/stuff/patch-scripts.tar.gz |
81 | Instead of these scripts, quilt is the recommended patch management | 81 | Instead of these scripts, quilt is the recommended patch management |
82 | tool (see above). | 82 | tool (see above). |
83 | 83 | ||
@@ -405,7 +405,7 @@ person it names. This tag documents that potentially interested parties | |||
405 | have been included in the discussion | 405 | have been included in the discussion |
406 | 406 | ||
407 | 407 | ||
408 | 14) Using Test-by: and Reviewed-by: | 408 | 14) Using Tested-by: and Reviewed-by: |
409 | 409 | ||
410 | A Tested-by: tag indicates that the patch has been successfully tested (in | 410 | A Tested-by: tag indicates that the patch has been successfully tested (in |
411 | some environment) by the person named. This tag informs maintainers that | 411 | some environment) by the person named. This tag informs maintainers that |
@@ -653,7 +653,7 @@ SECTION 3 - REFERENCES | |||
653 | ---------------------- | 653 | ---------------------- |
654 | 654 | ||
655 | Andrew Morton, "The perfect patch" (tpp). | 655 | Andrew 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 | ||
658 | Jeff Garzik, "Linux kernel patch submission format". | 658 | Jeff 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 | ||
673 | Linus Torvalds's mail on the canonical patch format: | 673 | Linus 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 | |||
676 | Andi 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 | |||
7 | This KGDB patch enables the kernel developer to do source level debugging on | ||
8 | the kernel for the Blackfin architecture. The debugging works over either the | ||
9 | ethernet interface or one of the uarts. Both software breakpoints and | ||
10 | hardware breakpoints are supported in this version. | ||
11 | http://docs.blackfin.uclinux.org/doku.php?id=kgdb | ||
12 | |||
13 | |||
14 | 2 known issues: | ||
15 | 1. 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. | ||
19 | 2. 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 | |||
24 | Debug over Ethernet: | ||
25 | |||
26 | 1. Compile and install the cross platform version of gdb for blackfin, which | ||
27 | can be found at $(BINROOT)/bfin-elf-gdb. | ||
28 | |||
29 | 2. 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 | |||
34 | 3. 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 | |||
37 | 4. Connect minicom to the serial port and boot the kernel image. | ||
38 | |||
39 | 5. Configure the IP "/> ifconfig eth0 target-IP" | ||
40 | |||
41 | 6. Start GDB client "bfin-elf-gdb vmlinux". | ||
42 | |||
43 | 7. Connect to the target "(gdb) target remote udp:target-IP:6443". | ||
44 | |||
45 | 8. Set software breakpoint "(gdb) break sys_open". | ||
46 | |||
47 | 9. Continue "(gdb) c". | ||
48 | |||
49 | 10. Run ls in the target console "/> ls". | ||
50 | |||
51 | 11. Breakpoint hits. "Breakpoint 1: sys_open(..." | ||
52 | |||
53 | 12. Display local variables and function paramters. | ||
54 | (*) This operation gives wrong results, see known issue 1. | ||
55 | |||
56 | 13. Single stepping "(gdb) si". | ||
57 | |||
58 | 14. Remove breakpoint 1. "(gdb) del 1" | ||
59 | |||
60 | 15. Set hardware breakpoint "(gdb) hbreak sys_open". | ||
61 | |||
62 | 16. Continue "(gdb) c". | ||
63 | |||
64 | 17. Run ls in the target console "/> ls". | ||
65 | |||
66 | 18. Hardware breakpoint hits. "Breakpoint 1: sys_open(...". | ||
67 | (*) This hardware breakpoint will not be hit, see known issue 2. | ||
68 | |||
69 | 19. Continue "(gdb) c". | ||
70 | |||
71 | 20. Interrupt the target in GDB "Ctrl+C". | ||
72 | |||
73 | 21. Detach from the target "(gdb) detach". | ||
74 | |||
75 | 22. Exit GDB "(gdb) quit". | ||
76 | |||
77 | |||
78 | Debug over the UART: | ||
79 | |||
80 | 1. Compile and install the cross platform version of gdb for blackfin, which | ||
81 | can be found at $(BINROOT)/bfin-elf-gdb. | ||
82 | |||
83 | 2. 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 | |||
88 | 3. 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 | |||
92 | 4. If you want connect to kgdb when the kernel boots, enable | ||
93 | "KGDB: Wait for gdb connection early" | ||
94 | |||
95 | 5. Compile kernel. | ||
96 | |||
97 | 6. Connect minicom to the serial port of the console and boot the kernel image. | ||
98 | |||
99 | 7. Start GDB client "bfin-elf-gdb vmlinux". | ||
100 | |||
101 | 8. Set the baud rate in GDB "(gdb) set remotebaud 57600". | ||
102 | |||
103 | 9. Connect to the target on the second serial port "(gdb) target remote /dev/ttyS1". | ||
104 | |||
105 | 10. Set software breakpoint "(gdb) break sys_open". | ||
106 | |||
107 | 11. Continue "(gdb) c". | ||
108 | |||
109 | 12. Run ls in the target console "/> ls". | ||
110 | |||
111 | 13. A breakpoint is hit. "Breakpoint 1: sys_open(..." | ||
112 | |||
113 | 14. All other operations are the same as that in KGDB over Ethernet. | ||
114 | |||
115 | |||
116 | Debug over the same UART as console: | ||
117 | |||
118 | 1. Compile and install the cross platform version of gdb for blackfin, which | ||
119 | can be found at $(BINROOT)/bfin-elf-gdb. | ||
120 | |||
121 | 2. 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 | |||
126 | 3. 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 | |||
130 | 4. If you want connect to kgdb when the kernel boots, enable | ||
131 | "KGDB: Wait for gdb connection early" | ||
132 | |||
133 | 5. Connect minicom to the serial port and boot the kernel image. | ||
134 | |||
135 | 6. (Optional) Ask target to wait for gdb connection by entering Ctrl+A. In minicom, you should enter Ctrl+A+A. | ||
136 | |||
137 | 7. Start GDB client "bfin-elf-gdb vmlinux". | ||
138 | |||
139 | 8. Set the baud rate in GDB "(gdb) set remotebaud 57600". | ||
140 | |||
141 | 9. Connect to the target "(gdb) target remote /dev/ttyS0". | ||
142 | |||
143 | 10. Set software breakpoint "(gdb) break sys_open". | ||
144 | |||
145 | 11. Continue "(gdb) c". Then enter Ctrl+C twice to stop GDB connection. | ||
146 | |||
147 | 12. Run ls in the target console "/> ls". Dummy string can be seen on the console. | ||
148 | |||
149 | 13. 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 | |||
152 | 14. 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 | ||
249 | 6.3 PASSING EXISTING INTEGRITY METADATA | 249 | 5.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 | ||
286 | 6.4 REGISTERING A BLOCK DEVICE AS CAPABLE OF EXCHANGING INTEGRITY | 286 | 5.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) | |||
30 | Similar to read_expire mentioned above, but for writes. | 30 | Similar to read_expire mentioned above, but for writes. |
31 | 31 | ||
32 | 32 | ||
33 | fifo_batch | 33 | fifo_batch (number of requests) |
34 | ---------- | 34 | ---------- |
35 | 35 | ||
36 | When a read request expires its deadline, we must move some requests from | 36 | Requests are grouped into ``batches'' of a particular data direction (read or |
37 | the sorted io scheduler list to the block device dispatch queue. fifo_batch | 37 | write) which are serviced in increasing sector order. To limit extra seeking, |
38 | controls how many requests we move. | 38 | deadline expiries are only checked between batches. fifo_batch controls the |
39 | maximum number of requests per batch. | ||
40 | |||
41 | This parameter tunes the balance between per-request latency and aggregate | ||
42 | throughput. When low latency is the primary concern, smaller is better (where | ||
43 | a value of 1 yields first-come first-served behaviour). Increasing fifo_batch | ||
44 | generally improves throughput, at the cost of latency variation. | ||
39 | 45 | ||
40 | 46 | ||
41 | writes_starved (number of dispatches) | 47 | writes_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 | ||
146 | To play an audio CD, you should first unmount and remove any data | 146 | To play an audio CD, you should first unmount and remove any data |
147 | CDROM. Any of the CDROM player programs should then work (workman, | 147 | CDROM. Any of the CDROM player programs should then work (workman, |
148 | workbone, cdplayer, etc.). Lacking anything else, you could use the | 148 | workbone, cdplayer, etc.). |
149 | cdtester program in Documentation/cdrom/sbpcd. | ||
150 | 149 | ||
151 | On a few drives, you can read digital audio directly using a program | 150 | On a few drives, you can read digital audio directly using a program |
152 | such as cdda2wav. The only types of drive which I've heard support | 151 | such 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. | |||
27 | The ETRAX 100LX chip | 27 | The ETRAX 100LX chip |
28 | -------------------- | 28 | -------------------- |
29 | 29 | ||
30 | For reference, plase see the press-release: | 30 | For reference, please see the press-release: |
31 | 31 | ||
32 | http://www.axis.com/news/us/001101_etrax.htm | 32 | http://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 @@ | |||
1 | 1: A GUIDE TO THE KERNEL DEVELOPMENT PROCESS | ||
2 | |||
3 | The purpose of this document is to help developers (and their managers) | ||
4 | work with the development community with a minimum of frustration. It is | ||
5 | an attempt to document how this community works in a way which is | ||
6 | accessible to those who are not intimately familiar with Linux kernel | ||
7 | development (or, indeed, free software development in general). While | ||
8 | there is some technical material here, this is very much a process-oriented | ||
9 | discussion which does not require a deep knowledge of kernel programming to | ||
10 | understand. | ||
11 | |||
12 | |||
13 | 1.1: EXECUTIVE SUMMARY | ||
14 | |||
15 | The rest of this section covers the scope of the kernel development process | ||
16 | and the kinds of frustrations that developers and their employers can | ||
17 | encounter there. There are a great many reasons why kernel code should be | ||
18 | merged into the official ("mainline") kernel, including automatic | ||
19 | availability to users, community support in many forms, and the ability to | ||
20 | influence the direction of kernel development. Code contributed to the | ||
21 | Linux kernel must be made available under a GPL-compatible license. | ||
22 | |||
23 | Section 2 introduces the development process, the kernel release cycle, and | ||
24 | the mechanics of the merge window. The various phases in the patch | ||
25 | development, review, and merging cycle are covered. There is some | ||
26 | discussion of tools and mailing lists. Developers wanting to get started | ||
27 | with kernel development are encouraged to track down and fix bugs as an | ||
28 | initial exercise. | ||
29 | |||
30 | Section 3 covers early-stage project planning, with an emphasis on | ||
31 | involving the development community as soon as possible. | ||
32 | |||
33 | Section 4 is about the coding process; several pitfalls which have been | ||
34 | encountered by other developers are discussed. Some requirements for | ||
35 | patches are covered, and there is an introduction to some of the tools | ||
36 | which can help to ensure that kernel patches are correct. | ||
37 | |||
38 | Section 5 talks about the process of posting patches for review. To be | ||
39 | taken seriously by the development community, patches must be properly | ||
40 | formatted and described, and they must be sent to the right place. | ||
41 | Following the advice in this section should help to ensure the best | ||
42 | possible reception for your work. | ||
43 | |||
44 | Section 6 covers what happens after posting patches; the job is far from | ||
45 | done at that point. Working with reviewers is a crucial part of the | ||
46 | development process; this section offers a number of tips on how to avoid | ||
47 | problems at this important stage. Developers are cautioned against | ||
48 | assuming that the job is done when a patch is merged into the mainline. | ||
49 | |||
50 | Section 7 introduces a couple of "advanced" topics: managing patches with | ||
51 | git and reviewing patches posted by others. | ||
52 | |||
53 | Section 8 concludes the document with pointers to sources for more | ||
54 | information on kernel development. | ||
55 | |||
56 | |||
57 | 1.2: WHAT THIS DOCUMENT IS ABOUT | ||
58 | |||
59 | The Linux kernel, at over 6 million lines of code and well over 1000 active | ||
60 | contributors, is one of the largest and most active free software projects | ||
61 | in existence. Since its humble beginning in 1991, this kernel has evolved | ||
62 | into a best-of-breed operating system component which runs on pocket-sized | ||
63 | digital music players, desktop PCs, the largest supercomputers in | ||
64 | existence, and all types of systems in between. It is a robust, efficient, | ||
65 | and scalable solution for almost any situation. | ||
66 | |||
67 | With the growth of Linux has come an increase in the number of developers | ||
68 | (and companies) wishing to participate in its development. Hardware | ||
69 | vendors want to ensure that Linux supports their products well, making | ||
70 | those products attractive to Linux users. Embedded systems vendors, who | ||
71 | use Linux as a component in an integrated product, want Linux to be as | ||
72 | capable and well-suited to the task at hand as possible. Distributors and | ||
73 | other software vendors who base their products on Linux have a clear | ||
74 | interest in the capabilities, performance, and reliability of the Linux | ||
75 | kernel. And end users, too, will often wish to change Linux to make it | ||
76 | better suit their needs. | ||
77 | |||
78 | One of the most compelling features of Linux is that it is accessible to | ||
79 | these developers; anybody with the requisite skills can improve Linux and | ||
80 | influence the direction of its development. Proprietary products cannot | ||
81 | offer this kind of openness, which is a characteristic of the free software | ||
82 | process. But, if anything, the kernel is even more open than most other | ||
83 | free software projects. A typical three-month kernel development cycle can | ||
84 | involve over 1000 developers working for more than 100 different companies | ||
85 | (or for no company at all). | ||
86 | |||
87 | Working with the kernel development community is not especially hard. But, | ||
88 | that notwithstanding, many potential contributors have experienced | ||
89 | difficulties when trying to do kernel work. The kernel community has | ||
90 | evolved its own distinct ways of operating which allow it to function | ||
91 | smoothly (and produce a high-quality product) in an environment where | ||
92 | thousands of lines of code are being changed every day. So it is not | ||
93 | surprising that Linux kernel development process differs greatly from | ||
94 | proprietary development methods. | ||
95 | |||
96 | The kernel's development process may come across as strange and | ||
97 | intimidating to new developers, but there are good reasons and solid | ||
98 | experience behind it. A developer who does not understand the kernel | ||
99 | community's ways (or, worse, who tries to flout or circumvent them) will | ||
100 | have a frustrating experience in store. The development community, while | ||
101 | being helpful to those who are trying to learn, has little time for those | ||
102 | who will not listen or who do not care about the development process. | ||
103 | |||
104 | It is hoped that those who read this document will be able to avoid that | ||
105 | frustrating experience. There is a lot of material here, but the effort | ||
106 | involved in reading it will be repaid in short order. The development | ||
107 | community is always in need of developers who will help to make the kernel | ||
108 | better; the following text should help you - or those who work for you - | ||
109 | join our community. | ||
110 | |||
111 | |||
112 | 1.3: CREDITS | ||
113 | |||
114 | This document was written by Jonathan Corbet, corbet@lwn.net. It has been | ||
115 | improved by comments from Johannes Berg, James Berry, Alex Chiang, Roland | ||
116 | Dreier, Randy Dunlap, Jake Edge, Jiri Kosina, Matt Mackall, Arthur Marsh, | ||
117 | Amanda McPherson, Andrew Morton, Andrew Price, Tsugikazu Shibata, and | ||
118 | Jochen Voß. | ||
119 | |||
120 | This work was supported by the Linux Foundation; thanks especially to | ||
121 | Amanda McPherson, who saw the value of this effort and made it all happen. | ||
122 | |||
123 | |||
124 | 1.4: THE IMPORTANCE OF GETTING CODE INTO THE MAINLINE | ||
125 | |||
126 | Some companies and developers occasionally wonder why they should bother | ||
127 | learning how to work with the kernel community and get their code into the | ||
128 | mainline kernel (the "mainline" being the kernel maintained by Linus | ||
129 | Torvalds and used as a base by Linux distributors). In the short term, | ||
130 | contributing code can look like an avoidable expense; it seems easier to | ||
131 | just keep the code separate and support users directly. The truth of the | ||
132 | matter is that keeping code separate ("out of tree") is a false economy. | ||
133 | |||
134 | As a way of illustrating the costs of out-of-tree code, here are a few | ||
135 | relevant aspects of the kernel development process; most of these will be | ||
136 | discussed 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 | |||
193 | All of the reasoning above applies to any out-of-tree kernel code, | ||
194 | including code which is distributed in proprietary, binary-only form. | ||
195 | There are, however, additional factors which should be taken into account | ||
196 | before considering any sort of binary-only kernel code distribution. These | ||
197 | include: | ||
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 | |||
226 | Makers of embedded systems, in particular, may be tempted to disregard much | ||
227 | of what has been said in this section in the belief that they are shipping | ||
228 | a self-contained product which uses a frozen kernel version and requires no | ||
229 | more development after its release. This argument misses the value of | ||
230 | widespread code review and the value of allowing your users to add | ||
231 | capabilities to your product. But these products, too, have a limited | ||
232 | commercial life, after which a new version must be released. At that | ||
233 | point, vendors whose code is in the mainline and well maintained will be | ||
234 | much better positioned to get the new product ready for market quickly. | ||
235 | |||
236 | |||
237 | 1.5: LICENSING | ||
238 | |||
239 | Code is contributed to the Linux kernel under a number of licenses, but all | ||
240 | code 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. | ||
242 | In practice, that means that all code contributions are covered either by | ||
243 | GPLv2 (with, optionally, language allowing distribution under later | ||
244 | versions of the GPL) or the three-clause BSD license. Any contributions | ||
245 | which are not covered by a compatible license will not be accepted into the | ||
246 | kernel. | ||
247 | |||
248 | Copyright assignments are not required (or requested) for code contributed | ||
249 | to the kernel. All code merged into the mainline kernel retains its | ||
250 | original ownership; as a result, the kernel now has thousands of owners. | ||
251 | |||
252 | One implication of this ownership structure is that any attempt to change | ||
253 | the licensing of the kernel is doomed to almost certain failure. There are | ||
254 | few practical scenarios where the agreement of all copyright holders could | ||
255 | be obtained (or their code removed from the kernel). So, in particular, | ||
256 | there is no prospect of a migration to version 3 of the GPL in the | ||
257 | foreseeable future. | ||
258 | |||
259 | It is imperative that all code contributed to the kernel be legitimately | ||
260 | free software. For that reason, code from anonymous (or pseudonymous) | ||
261 | contributors will not be accepted. All contributors are required to "sign | ||
262 | off" on their code, stating that the code can be distributed with the | ||
263 | kernel under the GPL. Code which has not been licensed as free software by | ||
264 | its owner, or which risks creating copyright-related problems for the | ||
265 | kernel (such as code which derives from reverse-engineering efforts lacking | ||
266 | proper safeguards) cannot be contributed. | ||
267 | |||
268 | Questions about copyright-related issues are common on Linux development | ||
269 | mailing lists. Such questions will normally receive no shortage of | ||
270 | answers, but one should bear in mind that the people answering those | ||
271 | questions are not lawyers and cannot provide legal advice. If you have | ||
272 | legal questions relating to Linux source code, there is no substitute for | ||
273 | talking with a lawyer who understands this field. Relying on answers | ||
274 | obtained 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 @@ | |||
1 | 2: HOW THE DEVELOPMENT PROCESS WORKS | ||
2 | |||
3 | Linux kernel development in the early 1990's was a pretty loose affair, | ||
4 | with relatively small numbers of users and developers involved. With a | ||
5 | user base in the millions and with some 2,000 developers involved over the | ||
6 | course of one year, the kernel has since had to evolve a number of | ||
7 | processes to keep development happening smoothly. A solid understanding of | ||
8 | how the process works is required in order to be an effective part of it. | ||
9 | |||
10 | |||
11 | 2.1: THE BIG PICTURE | ||
12 | |||
13 | The kernel developers use a loosely time-based release process, with a new | ||
14 | major kernel release happening every two or three months. The recent | ||
15 | release 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 | |||
25 | Every 2.6.x release is a major kernel release with new features, internal | ||
26 | API changes, and more. A typical 2.6 release can contain over 10,000 | ||
27 | changesets with changes to several hundred thousand lines of code. 2.6 is | ||
28 | thus the leading edge of Linux kernel development; the kernel uses a | ||
29 | rolling development model which is continually integrating major changes. | ||
30 | |||
31 | A relatively straightforward discipline is followed with regard to the | ||
32 | merging of patches for each release. At the beginning of each development | ||
33 | cycle, the "merge window" is said to be open. At that time, code which is | ||
34 | deemed to be sufficiently stable (and which is accepted by the development | ||
35 | community) is merged into the mainline kernel. The bulk of changes for a | ||
36 | new development cycle (and all of the major changes) will be merged during | ||
37 | this time, at a rate approaching 1,000 changes ("patches," or "changesets") | ||
38 | per day. | ||
39 | |||
40 | (As an aside, it is worth noting that the changes integrated during the | ||
41 | merge window do not come out of thin air; they have been collected, tested, | ||
42 | and staged ahead of time. How that process works will be described in | ||
43 | detail later on). | ||
44 | |||
45 | The merge window lasts for two weeks. At the end of this time, Linus | ||
46 | Torvalds will declare that the window is closed and release the first of | ||
47 | the "rc" kernels. For the kernel which is destined to be 2.6.26, for | ||
48 | example, the release which happens at the end of the merge window will be | ||
49 | called 2.6.26-rc1. The -rc1 release is the signal that the time to merge | ||
50 | new features has passed, and that the time to stabilize the next kernel has | ||
51 | begun. | ||
52 | |||
53 | Over the next six to ten weeks, only patches which fix problems should be | ||
54 | submitted to the mainline. On occasion a more significant change will be | ||
55 | allowed, but such occasions are rare; developers who try to merge new | ||
56 | features outside of the merge window tend to get an unfriendly reception. | ||
57 | As a general rule, if you miss the merge window for a given feature, the | ||
58 | best thing to do is to wait for the next development cycle. (An occasional | ||
59 | exception is made for drivers for previously-unsupported hardware; if they | ||
60 | touch no in-tree code, they cannot cause regressions and should be safe to | ||
61 | add at any time). | ||
62 | |||
63 | As fixes make their way into the mainline, the patch rate will slow over | ||
64 | time. Linus releases new -rc kernels about once a week; a normal series | ||
65 | will get up to somewhere between -rc6 and -rc9 before the kernel is | ||
66 | considered to be sufficiently stable and the final 2.6.x release is made. | ||
67 | At that point the whole process starts over again. | ||
68 | |||
69 | As an example, here is how the 2.6.25 development cycle went (all dates in | ||
70 | 2008): | ||
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 | |||
84 | How do the developers decide when to close the development cycle and create | ||
85 | the stable release? The most significant metric used is the list of | ||
86 | regressions from previous releases. No bugs are welcome, but those which | ||
87 | break systems which worked in the past are considered to be especially | ||
88 | serious. For this reason, patches which cause regressions are looked upon | ||
89 | unfavorably and are quite likely to be reverted during the stabilization | ||
90 | period. | ||
91 | |||
92 | The developers' goal is to fix all known regressions before the stable | ||
93 | release is made. In the real world, this kind of perfection is hard to | ||
94 | achieve; there are just too many variables in a project of this size. | ||
95 | There comes a point where delaying the final release just makes the problem | ||
96 | worse; the pile of changes waiting for the next merge window will grow | ||
97 | larger, creating even more regressions the next time around. So most 2.6.x | ||
98 | kernels go out with a handful of known regressions though, hopefully, none | ||
99 | of them are serious. | ||
100 | |||
101 | Once 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. | ||
103 | The stable team will release occasional updates to the stable release using | ||
104 | the 2.6.x.y numbering scheme. To be considered for an update release, a | ||
105 | patch must (1) fix a significant bug, and (2) already be merged into the | ||
106 | mainline for the next development kernel. Continuing our 2.6.25 example, | ||
107 | the 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 | |||
119 | Stable updates for a given kernel are made for approximately six months; | ||
120 | after that, the maintenance of stable releases is solely the responsibility | ||
121 | of the distributors which have shipped that particular kernel. | ||
122 | |||
123 | |||
124 | 2.2: THE LIFECYCLE OF A PATCH | ||
125 | |||
126 | Patches do not go directly from the developer's keyboard into the mainline | ||
127 | kernel. There is, instead, a somewhat involved (if somewhat informal) | ||
128 | process designed to ensure that each patch is reviewed for quality and that | ||
129 | each patch implements a change which is desirable to have in the mainline. | ||
130 | This process can happen quickly for minor fixes, or, in the case of large | ||
131 | and controversial changes, go on for years. Much developer frustration | ||
132 | comes from a lack of understanding of this process or from attempts to | ||
133 | circumvent it. | ||
134 | |||
135 | In the hopes of reducing that frustration, this document will describe how | ||
136 | a patch gets into the kernel. What follows below is an introduction which | ||
137 | describes the process in a somewhat idealized way. A much more detailed | ||
138 | treatment will come in later sections. | ||
139 | |||
140 | The 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 | |||
178 | One of the largest mistakes made by kernel developers (or their employers) | ||
179 | is to try to cut the process down to a single "merging into the mainline" | ||
180 | step. This approach invariably leads to frustration for everybody | ||
181 | involved. | ||
182 | |||
183 | |||
184 | 2.3: HOW PATCHES GET INTO THE KERNEL | ||
185 | |||
186 | There is exactly one person who can merge patches into the mainline kernel | ||
187 | repository: Linus Torvalds. But, of the over 12,000 patches which went | ||
188 | into the 2.6.25 kernel, only 250 (around 2%) were directly chosen by Linus | ||
189 | himself. The kernel project has long since grown to a size where no single | ||
190 | developer could possibly inspect and select every patch unassisted. The | ||
191 | way the kernel developers have addressed this growth is through the use of | ||
192 | a lieutenant system built around a chain of trust. | ||
193 | |||
194 | The kernel code base is logically broken down into a set of subsystems: | ||
195 | networking, specific architecture support, memory management, video | ||
196 | devices, etc. Most subsystems have a designated maintainer, a developer | ||
197 | who has overall responsibility for the code within that subsystem. These | ||
198 | subsystem maintainers are the gatekeepers (in a loose way) for the portion | ||
199 | of the kernel they manage; they are the ones who will (usually) accept a | ||
200 | patch for inclusion into the mainline kernel. | ||
201 | |||
202 | Subsystem maintainers each manage their own version of the kernel source | ||
203 | tree, usually (but certainly not always) using the git source management | ||
204 | tool. Tools like git (and related tools like quilt or mercurial) allow | ||
205 | maintainers to track a list of patches, including authorship information | ||
206 | and other metadata. At any given time, the maintainer can identify which | ||
207 | patches in his or her repository are not found in the mainline. | ||
208 | |||
209 | When the merge window opens, top-level maintainers will ask Linus to "pull" | ||
210 | the patches they have selected for merging from their repositories. If | ||
211 | Linus agrees, the stream of patches will flow up into his repository, | ||
212 | becoming part of the mainline kernel. The amount of attention that Linus | ||
213 | pays to specific patches received in a pull operation varies. It is clear | ||
214 | that, sometimes, he looks quite closely. But, as a general rule, Linus | ||
215 | trusts the subsystem maintainers to not send bad patches upstream. | ||
216 | |||
217 | Subsystem maintainers, in turn, can pull patches from other maintainers. | ||
218 | For example, the networking tree is built from patches which accumulated | ||
219 | first in trees dedicated to network device drivers, wireless networking, | ||
220 | etc. This chain of repositories can be arbitrarily long, though it rarely | ||
221 | exceeds two or three links. Since each maintainer in the chain trusts | ||
222 | those managing lower-level trees, this process is known as the "chain of | ||
223 | trust." | ||
224 | |||
225 | Clearly, in a system like this, getting patches into the kernel depends on | ||
226 | finding the right maintainer. Sending patches directly to Linus is not | ||
227 | normally the right way to go. | ||
228 | |||
229 | |||
230 | 2.4: STAGING TREES | ||
231 | |||
232 | The chain of subsystem trees guides the flow of patches into the kernel, | ||
233 | but it also raises an interesting question: what if somebody wants to look | ||
234 | at all of the patches which are being prepared for the next merge window? | ||
235 | Developers will be interested in what other changes are pending to see | ||
236 | whether there are any conflicts to worry about; a patch which changes a | ||
237 | core kernel function prototype, for example, will conflict with any other | ||
238 | patches which use the older form of that function. Reviewers and testers | ||
239 | want access to the changes in their integrated form before all of those | ||
240 | changes land in the mainline kernel. One could pull changes from all of | ||
241 | the interesting subsystem trees, but that would be a big and error-prone | ||
242 | job. | ||
243 | |||
244 | The answer comes in the form of staging trees, where subsystem trees are | ||
245 | collected for testing and review. The older of these trees, maintained by | ||
246 | Andrew Morton, is called "-mm" (for memory management, which is how it got | ||
247 | started). The -mm tree integrates patches from a long list of subsystem | ||
248 | trees; it also has some patches aimed at helping with debugging. | ||
249 | |||
250 | Beyond that, -mm contains a significant collection of patches which have | ||
251 | been selected by Andrew directly. These patches may have been posted on a | ||
252 | mailing list, or they may apply to a part of the kernel for which there is | ||
253 | no designated subsystem tree. As a result, -mm operates as a sort of | ||
254 | subsystem tree of last resort; if there is no other obvious path for a | ||
255 | patch into the mainline, it is likely to end up in -mm. Miscellaneous | ||
256 | patches which accumulate in -mm will eventually either be forwarded on to | ||
257 | an appropriate subsystem tree or be sent directly to Linus. In a typical | ||
258 | development cycle, approximately 10% of the patches going into the mainline | ||
259 | get there via -mm. | ||
260 | |||
261 | The current -mm patch can always be found from the front page of | ||
262 | |||
263 | http://kernel.org/ | ||
264 | |||
265 | Those who want to see the current state of -mm can get the "-mm of the | ||
266 | moment" tree, found at: | ||
267 | |||
268 | http://userweb.kernel.org/~akpm/mmotm/ | ||
269 | |||
270 | Use of the MMOTM tree is likely to be a frustrating experience, though; | ||
271 | there is a definite chance that it will not even compile. | ||
272 | |||
273 | The other staging tree, started more recently, is linux-next, maintained by | ||
274 | Stephen Rothwell. The linux-next tree is, by design, a snapshot of what | ||
275 | the mainline is expected to look like after the next merge window closes. | ||
276 | Linux-next trees are announced on the linux-kernel and linux-next mailing | ||
277 | lists when they are assembled; they can be downloaded from: | ||
278 | |||
279 | http://www.kernel.org/pub/linux/kernel/people/sfr/linux-next/ | ||
280 | |||
281 | Some information about linux-next has been gathered at: | ||
282 | |||
283 | http://linux.f-seidel.de/linux-next/pmwiki/ | ||
284 | |||
285 | How the linux-next tree will fit into the development process is still | ||
286 | changing. As of this writing, the first full development cycle involving | ||
287 | linux-next (2.6.26) is coming to an end; thus far, it has proved to be a | ||
288 | valuable resource for finding and fixing integration problems before the | ||
289 | beginning of the merge window. See http://lwn.net/Articles/287155/ for | ||
290 | more information on how linux-next has worked to set up the 2.6.27 merge | ||
291 | window. | ||
292 | |||
293 | Some developers have begun to suggest that linux-next should be used as the | ||
294 | target for future development as well. The linux-next tree does tend to be | ||
295 | far ahead of the mainline and is more representative of the tree into which | ||
296 | any new work will be merged. The downside to this idea is that the | ||
297 | volatility of linux-next tends to make it a difficult development target. | ||
298 | See http://lwn.net/Articles/289013/ for more information on this topic, and | ||
299 | stay tuned; much is still in flux where linux-next is involved. | ||
300 | |||
301 | |||
302 | 2.5: TOOLS | ||
303 | |||
304 | As can be seen from the above text, the kernel development process depends | ||
305 | heavily on the ability to herd collections of patches in various | ||
306 | directions. The whole thing would not work anywhere near as well as it | ||
307 | does without suitably powerful tools. Tutorials on how to use these tools | ||
308 | are well beyond the scope of this document, but there is space for a few | ||
309 | pointers. | ||
310 | |||
311 | By far the dominant source code management system used by the kernel | ||
312 | community is git. Git is one of a number of distributed version control | ||
313 | systems being developed in the free software community. It is well tuned | ||
314 | for kernel development, in that it performs quite well when dealing with | ||
315 | large repositories and large numbers of patches. It also has a reputation | ||
316 | for being difficult to learn and use, though it has gotten better over | ||
317 | time. Some sort of familiarity with git is almost a requirement for kernel | ||
318 | developers; even if they do not use it for their own work, they'll need git | ||
319 | to keep up with what other developers (and the mainline) are doing. | ||
320 | |||
321 | Git is now packaged by almost all Linux distributions. There is a home | ||
322 | page at | ||
323 | |||
324 | http://git.or.cz/ | ||
325 | |||
326 | That page has pointers to documentation and tutorials. One should be | ||
327 | aware, in particular, of the Kernel Hacker's Guide to git, which has | ||
328 | information specific to kernel development: | ||
329 | |||
330 | http://linux.yyz.us/git-howto.html | ||
331 | |||
332 | Among the kernel developers who do not use git, the most popular choice is | ||
333 | almost certainly Mercurial: | ||
334 | |||
335 | http://www.selenic.com/mercurial/ | ||
336 | |||
337 | Mercurial shares many features with git, but it provides an interface which | ||
338 | many find easier to use. | ||
339 | |||
340 | The other tool worth knowing about is Quilt: | ||
341 | |||
342 | http://savannah.nongnu.org/projects/quilt/ | ||
343 | |||
344 | Quilt is a patch management system, rather than a source code management | ||
345 | system. It does not track history over time; it is, instead, oriented | ||
346 | toward tracking a specific set of changes against an evolving code base. | ||
347 | Some major subsystem maintainers use quilt to manage patches intended to go | ||
348 | upstream. For the management of certain kinds of trees (-mm, for example), | ||
349 | quilt is the best tool for the job. | ||
350 | |||
351 | |||
352 | 2.6: MAILING LISTS | ||
353 | |||
354 | A great deal of Linux kernel development work is done by way of mailing | ||
355 | lists. It is hard to be a fully-functioning member of the community | ||
356 | without joining at least one list somewhere. But Linux mailing lists also | ||
357 | represent a potential hazard to developers, who risk getting buried under a | ||
358 | load of electronic mail, running afoul of the conventions used on the Linux | ||
359 | lists, or both. | ||
360 | |||
361 | Most kernel mailing lists are run on vger.kernel.org; the master list can | ||
362 | be found at: | ||
363 | |||
364 | http://vger.kernel.org/vger-lists.html | ||
365 | |||
366 | There are lists hosted elsewhere, though; a number of them are at | ||
367 | lists.redhat.com. | ||
368 | |||
369 | The core mailing list for kernel development is, of course, linux-kernel. | ||
370 | This list is an intimidating place to be; volume can reach 500 messages per | ||
371 | day, the amount of noise is high, the conversation can be severely | ||
372 | technical, and participants are not always concerned with showing a high | ||
373 | degree of politeness. But there is no other place where the kernel | ||
374 | development community comes together as a whole; developers who avoid this | ||
375 | list will miss important information. | ||
376 | |||
377 | There 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 | |||
411 | The last point - finding the correct mailing list - is a common place for | ||
412 | beginning developers to go wrong. Somebody who asks a networking-related | ||
413 | question on linux-kernel will almost certainly receive a polite suggestion | ||
414 | to ask on the netdev list instead, as that is the list frequented by most | ||
415 | networking developers. Other lists exist for the SCSI, video4linux, IDE, | ||
416 | filesystem, etc. subsystems. The best place to look for mailing lists is | ||
417 | in the MAINTAINERS file packaged with the kernel source. | ||
418 | |||
419 | |||
420 | 2.7: GETTING STARTED WITH KERNEL DEVELOPMENT | ||
421 | |||
422 | Questions about how to get started with the kernel development process are | ||
423 | common - from both individuals and companies. Equally common are missteps | ||
424 | which make the beginning of the relationship harder than it has to be. | ||
425 | |||
426 | Companies often look to hire well-known developers to get a development | ||
427 | group started. This can, in fact, be an effective technique. But it also | ||
428 | tends to be expensive and does not do much to grow the pool of experienced | ||
429 | kernel developers. It is possible to bring in-house developers up to speed | ||
430 | on Linux kernel development, given the investment of a bit of time. Taking | ||
431 | this time can endow an employer with a group of developers who understand | ||
432 | the kernel and the company both, and who can help to train others as well. | ||
433 | Over the medium term, this is often the more profitable approach. | ||
434 | |||
435 | Individual developers are often, understandably, at a loss for a place to | ||
436 | start. Beginning with a large project can be intimidating; one often wants | ||
437 | to test the waters with something smaller first. This is the point where | ||
438 | some developers jump into the creation of patches fixing spelling errors or | ||
439 | minor coding style issues. Unfortunately, such patches create a level of | ||
440 | noise which is distracting for the development community as a whole, so, | ||
441 | increasingly, they are looked down upon. New developers wishing to | ||
442 | introduce themselves to the community will not get the sort of reception | ||
443 | they wish for by these means. | ||
444 | |||
445 | Andrew 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 | |||
455 | In the absence of obvious problems to fix, developers are advised to look | ||
456 | at the current lists of regressions and open bugs in general. There is | ||
457 | never any shortage of issues in need of fixing; by addressing these issues, | ||
458 | developers will gain experience with the process while, at the same time, | ||
459 | building 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 @@ | |||
1 | 3: EARLY-STAGE PLANNING | ||
2 | |||
3 | When contemplating a Linux kernel development project, it can be tempting | ||
4 | to jump right in and start coding. As with any significant project, | ||
5 | though, much of the groundwork for success is best laid before the first | ||
6 | line of code is written. Some time spent in early planning and | ||
7 | communication can save far more time later on. | ||
8 | |||
9 | |||
10 | 3.1: SPECIFYING THE PROBLEM | ||
11 | |||
12 | Like any engineering project, a successful kernel enhancement starts with a | ||
13 | clear description of the problem to be solved. In some cases, this step is | ||
14 | easy: when a driver is needed for a specific piece of hardware, for | ||
15 | example. In others, though, it is tempting to confuse the real problem | ||
16 | with the proposed solution, and that can lead to difficulties. | ||
17 | |||
18 | Consider an example: some years ago, developers working with Linux audio | ||
19 | sought a way to run applications without dropouts or other artifacts caused | ||
20 | by excessive latency in the system. The solution they arrived at was a | ||
21 | kernel module intended to hook into the Linux Security Module (LSM) | ||
22 | framework; this module could be configured to give specific applications | ||
23 | access to the realtime scheduler. This module was implemented and sent to | ||
24 | the linux-kernel mailing list, where it immediately ran into problems. | ||
25 | |||
26 | To the audio developers, this security module was sufficient to solve their | ||
27 | immediate problem. To the wider kernel community, though, it was seen as a | ||
28 | misuse of the LSM framework (which is not intended to confer privileges | ||
29 | onto processes which they would not otherwise have) and a risk to system | ||
30 | stability. Their preferred solutions involved realtime scheduling access | ||
31 | via the rlimit mechanism for the short term, and ongoing latency reduction | ||
32 | work in the long term. | ||
33 | |||
34 | The audio community, however, could not see past the particular solution | ||
35 | they had implemented; they were unwilling to accept alternatives. The | ||
36 | resulting disagreement left those developers feeling disillusioned with the | ||
37 | entire kernel development process; one of them went back to an audio list | ||
38 | and 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 | |||
47 | The reality of the situation was different; the kernel developers were far | ||
48 | more concerned about system stability, long-term maintenance, and finding | ||
49 | the right solution to the problem than they were with a specific module. | ||
50 | The 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 | ||
52 | creation of a body of code. | ||
53 | |||
54 | So, when contemplating a kernel development project, one should obtain | ||
55 | answers 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 | |||
64 | Only then does it make sense to start considering possible solutions. | ||
65 | |||
66 | |||
67 | 3.2: EARLY DISCUSSION | ||
68 | |||
69 | When planning a kernel development project, it makes great sense to hold | ||
70 | discussions with the community before launching into implementation. Early | ||
71 | communication 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 | |||
90 | Years of experience with the kernel development community have taught a | ||
91 | clear lesson: kernel code which is designed and developed behind closed | ||
92 | doors invariably has problems which are only revealed when the code is | ||
93 | released into the community. Sometimes these problems are severe, | ||
94 | requiring months or years of effort before the code can be brought up to | ||
95 | the 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 | |||
116 | In each of these cases, a great deal of pain and extra work could have been | ||
117 | avoided with some early discussion with the kernel developers. | ||
118 | |||
119 | |||
120 | 3.3: WHO DO YOU TALK TO? | ||
121 | |||
122 | When developers decide to take their plans public, the next question will | ||
123 | be: where do we start? The answer is to find the right mailing list(s) and | ||
124 | the right maintainer. For mailing lists, the best approach is to look in | ||
125 | the MAINTAINERS file for a relevant place to post. If there is a suitable | ||
126 | subsystem list, posting there is often preferable to posting on | ||
127 | linux-kernel; you are more likely to reach developers with expertise in the | ||
128 | relevant subsystem and the environment may be more supportive. | ||
129 | |||
130 | Finding maintainers can be a bit harder. Again, the MAINTAINERS file is | ||
131 | the place to start. That file tends to not always be up to date, though, | ||
132 | and not all subsystems are represented there. The person listed in the | ||
133 | MAINTAINERS file may, in fact, not be the person who is actually acting in | ||
134 | that role currently. So, when there is doubt about who to contact, a | ||
135 | useful trick is to use git (and "git log" in particular) to see who is | ||
136 | currently active within the subsystem of interest. Look at who is writing | ||
137 | patches, and who, if anybody, is attaching Signed-off-by lines to those | ||
138 | patches. Those are the people who will be best placed to help with a new | ||
139 | development project. | ||
140 | |||
141 | If all else fails, talking to Andrew Morton can be an effective way to | ||
142 | track down a maintainer for a specific piece of code. | ||
143 | |||
144 | |||
145 | 3.4: WHEN TO POST? | ||
146 | |||
147 | If possible, posting your plans during the early stages can only be | ||
148 | helpful. Describe the problem being solved and any plans that have been | ||
149 | made on how the implementation will be done. Any information you can | ||
150 | provide can help the development community provide useful input on the | ||
151 | project. | ||
152 | |||
153 | One discouraging thing which can happen at this stage is not a hostile | ||
154 | reaction, but, instead, little or no reaction at all. The sad truth of the | ||
155 | matter is (1) kernel developers tend to be busy, (2) there is no shortage | ||
156 | of people with grand plans and little code (or even prospect of code) to | ||
157 | back them up, and (3) nobody is obligated to review or comment on ideas | ||
158 | posted by others. If a request-for-comments posting yields little in the | ||
159 | way of comments, do not assume that it means there is no interest in the | ||
160 | project. Unfortunately, you also cannot assume that there are no problems | ||
161 | with your idea. The best thing to do in this situation is to proceed, | ||
162 | keeping the community informed as you go. | ||
163 | |||
164 | |||
165 | 3.5: GETTING OFFICIAL BUY-IN | ||
166 | |||
167 | If your work is being done in a corporate environment - as most Linux | ||
168 | kernel work is - you must, obviously, have permission from suitably | ||
169 | empowered managers before you can post your company's plans or code to a | ||
170 | public mailing list. The posting of code which has not been cleared for | ||
171 | release under a GPL-compatible license can be especially problematic; the | ||
172 | sooner that a company's management and legal staff can agree on the posting | ||
173 | of a kernel development project, the better off everybody involved will be. | ||
174 | |||
175 | Some readers may be thinking at this point that their kernel work is | ||
176 | intended to support a product which does not yet have an officially | ||
177 | acknowledged existence. Revealing their employer's plans on a public | ||
178 | mailing list may not be a viable option. In cases like this, it is worth | ||
179 | considering whether the secrecy is really necessary; there is often no real | ||
180 | need to keep development plans behind closed doors. | ||
181 | |||
182 | That said, there are also cases where a company legitimately cannot | ||
183 | disclose its plans early in the development process. Companies with | ||
184 | experienced kernel developers may choose to proceed in an open-loop manner | ||
185 | on the assumption that they will be able to avoid serious integration | ||
186 | problems later. For companies without that sort of in-house expertise, the | ||
187 | best option is often to hire an outside developer to review the plans under | ||
188 | a non-disclosure agreement. The Linux Foundation operates an NDA program | ||
189 | designed to help with this sort of situation; more information can be found | ||
190 | at: | ||
191 | |||
192 | http://www.linuxfoundation.org/en/NDA_program | ||
193 | |||
194 | This kind of review is often enough to avoid serious problems later on | ||
195 | without 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 @@ | |||
1 | 4: GETTING THE CODE RIGHT | ||
2 | |||
3 | While there is much to be said for a solid and community-oriented design | ||
4 | process, the proof of any kernel development project is in the resulting | ||
5 | code. 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 | ||
7 | will determine the ultimate success of the project. | ||
8 | |||
9 | This section will examine the coding process. We'll start with a look at a | ||
10 | number of ways in which kernel developers can go wrong. Then the focus | ||
11 | will shift toward doing things right and the tools which can help in that | ||
12 | quest. | ||
13 | |||
14 | |||
15 | 4.1: PITFALLS | ||
16 | |||
17 | * Coding style | ||
18 | |||
19 | The kernel has long had a standard coding style, described in | ||
20 | Documentation/CodingStyle. For much of that time, the policies described | ||
21 | in that file were taken as being, at most, advisory. As a result, there is | ||
22 | a substantial amount of code in the kernel which does not meet the coding | ||
23 | style guidelines. The presence of that code leads to two independent | ||
24 | hazards for kernel developers. | ||
25 | |||
26 | The first of these is to believe that the kernel coding standards do not | ||
27 | matter and are not enforced. The truth of the matter is that adding new | ||
28 | code to the kernel is very difficult if that code is not coded according to | ||
29 | the standard; many developers will request that the code be reformatted | ||
30 | before they will even review it. A code base as large as the kernel | ||
31 | requires some uniformity of code to make it possible for developers to | ||
32 | quickly understand any part of it. So there is no longer room for | ||
33 | strangely-formatted code. | ||
34 | |||
35 | Occasionally, the kernel's coding style will run into conflict with an | ||
36 | employer's mandated style. In such cases, the kernel's style will have to | ||
37 | win before the code can be merged. Putting code into the kernel means | ||
38 | giving up a degree of control in a number of ways - including control over | ||
39 | how the code is formatted. | ||
40 | |||
41 | The other trap is to assume that code which is already in the kernel is | ||
42 | urgently in need of coding style fixes. Developers may start to generate | ||
43 | reformatting patches as a way of gaining familiarity with the process, or | ||
44 | as a way of getting their name into the kernel changelogs - or both. But | ||
45 | pure coding style fixes are seen as noise by the development community; | ||
46 | they tend to get a chilly reception. So this type of patch is best | ||
47 | avoided. It is natural to fix the style of a piece of code while working | ||
48 | on it for other reasons, but coding style changes should not be made for | ||
49 | their own sake. | ||
50 | |||
51 | The coding style document also should not be read as an absolute law which | ||
52 | can never be transgressed. If there is a good reason to go against the | ||
53 | style (a line which becomes far less readable if split to fit within the | ||
54 | 80-column limit, for example), just do it. | ||
55 | |||
56 | |||
57 | * Abstraction layers | ||
58 | |||
59 | Computer Science professors teach students to make extensive use of | ||
60 | abstraction layers in the name of flexibility and information hiding. | ||
61 | Certainly the kernel makes extensive use of abstraction; no project | ||
62 | involving several million lines of code could do otherwise and survive. | ||
63 | But experience has shown that excessive or premature abstraction can be | ||
64 | just as harmful as premature optimization. Abstraction should be used to | ||
65 | the level required and no further. | ||
66 | |||
67 | At a simple level, consider a function which has an argument which is | ||
68 | always passed as zero by all callers. One could retain that argument just | ||
69 | in case somebody eventually needs to use the extra flexibility that it | ||
70 | provides. By that time, though, chances are good that the code which | ||
71 | implements this extra argument has been broken in some subtle way which was | ||
72 | never noticed - because it has never been used. Or, when the need for | ||
73 | extra flexibility arises, it does not do so in a way which matches the | ||
74 | programmer's early expectation. Kernel developers will routinely submit | ||
75 | patches to remove unused arguments; they should, in general, not be added | ||
76 | in the first place. | ||
77 | |||
78 | Abstraction layers which hide access to hardware - often to allow the bulk | ||
79 | of a driver to be used with multiple operating systems - are especially | ||
80 | frowned upon. Such layers obscure the code and may impose a performance | ||
81 | penalty; they do not belong in the Linux kernel. | ||
82 | |||
83 | On the other hand, if you find yourself copying significant amounts of code | ||
84 | from another kernel subsystem, it is time to ask whether it would, in fact, | ||
85 | make sense to pull out some of that code into a separate library or to | ||
86 | implement that functionality at a higher level. There is no value in | ||
87 | replicating the same code throughout the kernel. | ||
88 | |||
89 | |||
90 | * #ifdef and preprocessor use in general | ||
91 | |||
92 | The C preprocessor seems to present a powerful temptation to some C | ||
93 | programmers, who see it as a way to efficiently encode a great deal of | ||
94 | flexibility into a source file. But the preprocessor is not C, and heavy | ||
95 | use of it results in code which is much harder for others to read and | ||
96 | harder for the compiler to check for correctness. Heavy preprocessor use | ||
97 | is almost always a sign of code which needs some cleanup work. | ||
98 | |||
99 | Conditional compilation with #ifdef is, indeed, a powerful feature, and it | ||
100 | is used within the kernel. But there is little desire to see code which is | ||
101 | sprinkled liberally with #ifdef blocks. As a general rule, #ifdef use | ||
102 | should be confined to header files whenever possible. | ||
103 | Conditionally-compiled code can be confined to functions which, if the code | ||
104 | is not to be present, simply become empty. The compiler will then quietly | ||
105 | optimize out the call to the empty function. The result is far cleaner | ||
106 | code which is easier to follow. | ||
107 | |||
108 | C preprocessor macros present a number of hazards, including possible | ||
109 | multiple evaluation of expressions with side effects and no type safety. | ||
110 | If you are tempted to define a macro, consider creating an inline function | ||
111 | instead. The code which results will be the same, but inline functions are | ||
112 | easier to read, do not evaluate their arguments multiple times, and allow | ||
113 | the compiler to perform type checking on the arguments and return value. | ||
114 | |||
115 | |||
116 | * Inline functions | ||
117 | |||
118 | Inline functions present a hazard of their own, though. Programmers can | ||
119 | become enamored of the perceived efficiency inherent in avoiding a function | ||
120 | call and fill a source file with inline functions. Those functions, | ||
121 | however, can actually reduce performance. Since their code is replicated | ||
122 | at each call site, they end up bloating the size of the compiled kernel. | ||
123 | That, in turn, creates pressure on the processor's memory caches, which can | ||
124 | slow execution dramatically. Inline functions, as a rule, should be quite | ||
125 | small and relatively rare. The cost of a function call, after all, is not | ||
126 | that high; the creation of large numbers of inline functions is a classic | ||
127 | example of premature optimization. | ||
128 | |||
129 | In general, kernel programmers ignore cache effects at their peril. The | ||
130 | classic time/space tradeoff taught in beginning data structures classes | ||
131 | often does not apply to contemporary hardware. Space *is* time, in that a | ||
132 | larger program will run slower than one which is more compact. | ||
133 | |||
134 | |||
135 | * Locking | ||
136 | |||
137 | In May, 2006, the "Devicescape" networking stack was, with great | ||
138 | fanfare, released under the GPL and made available for inclusion in the | ||
139 | mainline kernel. This donation was welcome news; support for wireless | ||
140 | networking in Linux was considered substandard at best, and the Devicescape | ||
141 | stack offered the promise of fixing that situation. Yet, this code did not | ||
142 | actually make it into the mainline until June, 2007 (2.6.22). What | ||
143 | happened? | ||
144 | |||
145 | This code showed a number of signs of having been developed behind | ||
146 | corporate doors. But one large problem in particular was that it was not | ||
147 | designed to work on multiprocessor systems. Before this networking stack | ||
148 | (now called mac80211) could be merged, a locking scheme needed to be | ||
149 | retrofitted onto it. | ||
150 | |||
151 | Once upon a time, Linux kernel code could be developed without thinking | ||
152 | about the concurrency issues presented by multiprocessor systems. Now, | ||
153 | however, this document is being written on a dual-core laptop. Even on | ||
154 | single-processor systems, work being done to improve responsiveness will | ||
155 | raise the level of concurrency within the kernel. The days when kernel | ||
156 | code could be written without thinking about locking are long past. | ||
157 | |||
158 | Any resource (data structures, hardware registers, etc.) which could be | ||
159 | accessed concurrently by more than one thread must be protected by a lock. | ||
160 | New code should be written with this requirement in mind; retrofitting | ||
161 | locking after the fact is a rather more difficult task. Kernel developers | ||
162 | should take the time to understand the available locking primitives well | ||
163 | enough to pick the right tool for the job. Code which shows a lack of | ||
164 | attention to concurrency will have a difficult path into the mainline. | ||
165 | |||
166 | |||
167 | * Regressions | ||
168 | |||
169 | One final hazard worth mentioning is this: it can be tempting to make a | ||
170 | change (which may bring big improvements) which causes something to break | ||
171 | for existing users. This kind of change is called a "regression," and | ||
172 | regressions have become most unwelcome in the mainline kernel. With few | ||
173 | exceptions, changes which cause regressions will be backed out if the | ||
174 | regression cannot be fixed in a timely manner. Far better to avoid the | ||
175 | regression in the first place. | ||
176 | |||
177 | It is often argued that a regression can be justified if it causes things | ||
178 | to work for more people than it creates problems for. Why not make a | ||
179 | change if it brings new functionality to ten systems for each one it | ||
180 | breaks? The best answer to this question was expressed by Linus in July, | ||
181 | 2007: | ||
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 | |||
190 | An especially unwelcome type of regression is any sort of change to the | ||
191 | user-space ABI. Once an interface has been exported to user space, it must | ||
192 | be supported indefinitely. This fact makes the creation of user-space | ||
193 | interfaces particularly challenging: since they cannot be changed in | ||
194 | incompatible ways, they must be done right the first time. For this | ||
195 | reason, a great deal of thought, clear documentation, and wide review for | ||
196 | user-space interfaces is always required. | ||
197 | |||
198 | |||
199 | |||
200 | 4.2: CODE CHECKING TOOLS | ||
201 | |||
202 | For now, at least, the writing of error-free code remains an ideal that few | ||
203 | of us can reach. What we can hope to do, though, is to catch and fix as | ||
204 | many of those errors as possible before our code goes into the mainline | ||
205 | kernel. To that end, the kernel developers have put together an impressive | ||
206 | array of tools which can catch a wide variety of obscure problems in an | ||
207 | automated way. Any problem caught by the computer is a problem which will | ||
208 | not afflict a user later on, so it stands to reason that the automated | ||
209 | tools should be used whenever possible. | ||
210 | |||
211 | The first step is simply to heed the warnings produced by the compiler. | ||
212 | Contemporary versions of gcc can detect (and warn about) a large number of | ||
213 | potential errors. Quite often, these warnings point to real problems. | ||
214 | Code submitted for review should, as a rule, not produce any compiler | ||
215 | warnings. When silencing warnings, take care to understand the real cause | ||
216 | and try to avoid "fixes" which make the warning go away without addressing | ||
217 | its cause. | ||
218 | |||
219 | Note that not all compiler warnings are enabled by default. Build the | ||
220 | kernel with "make EXTRA_CFLAGS=-W" to get the full set. | ||
221 | |||
222 | The kernel provides several configuration options which turn on debugging | ||
223 | features; most of these are found in the "kernel hacking" submenu. Several | ||
224 | of these options should be turned on for any kernel used for development or | ||
225 | testing 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 | |||
245 | There are quite a few other debugging options, some of which will be | ||
246 | discussed below. Some of them have a significant performance impact and | ||
247 | should not be used all of the time. But some time spent learning the | ||
248 | available options will likely be paid back many times over in short order. | ||
249 | |||
250 | One of the heavier debugging tools is the locking checker, or "lockdep." | ||
251 | This tool will track the acquisition and release of every lock (spinlock or | ||
252 | mutex) in the system, the order in which locks are acquired relative to | ||
253 | each other, the current interrupt environment, and more. It can then | ||
254 | ensure that locks are always acquired in the same order, that the same | ||
255 | interrupt assumptions apply in all situations, and so on. In other words, | ||
256 | lockdep can find a number of scenarios in which the system could, on rare | ||
257 | occasion, deadlock. This kind of problem can be painful (for both | ||
258 | developers and users) in a deployed system; lockdep allows them to be found | ||
259 | in an automated manner ahead of time. Code with any sort of non-trivial | ||
260 | locking should be run with lockdep enabled before being submitted for | ||
261 | inclusion. | ||
262 | |||
263 | As a diligent kernel programmer, you will, beyond doubt, check the return | ||
264 | status of any operation (such as a memory allocation) which can fail. The | ||
265 | fact of the matter, though, is that the resulting failure recovery paths | ||
266 | are, probably, completely untested. Untested code tends to be broken code; | ||
267 | you could be much more confident of your code if all those error-handling | ||
268 | paths had been exercised a few times. | ||
269 | |||
270 | The kernel provides a fault injection framework which can do exactly that, | ||
271 | especially where memory allocations are involved. With fault injection | ||
272 | enabled, a configurable percentage of memory allocations will be made to | ||
273 | fail; these failures can be restricted to a specific range of code. | ||
274 | Running with fault injection enabled allows the programmer to see how the | ||
275 | code responds when things go badly. See | ||
276 | Documentation/fault-injection/fault-injection.text for more information on | ||
277 | how to use this facility. | ||
278 | |||
279 | Other kinds of errors can be found with the "sparse" static analysis tool. | ||
280 | With sparse, the programmer can be warned about confusion between | ||
281 | user-space and kernel-space addresses, mixture of big-endian and | ||
282 | small-endian quantities, the passing of integer values where a set of bit | ||
283 | flags is expected, and so on. Sparse must be installed separately (it can | ||
284 | be found at http://www.kernel.org/pub/software/devel/sparse/ if your | ||
285 | distributor does not package it); it can then be run on the code by adding | ||
286 | "C=1" to your make command. | ||
287 | |||
288 | Other kinds of portability errors are best found by compiling your code for | ||
289 | other architectures. If you do not happen to have an S/390 system or a | ||
290 | Blackfin development board handy, you can still perform the compilation | ||
291 | step. A large set of cross compilers for x86 systems can be found at | ||
292 | |||
293 | http://www.kernel.org/pub/tools/crosstool/ | ||
294 | |||
295 | Some time spent installing and using these compilers will help avoid | ||
296 | embarrassment later. | ||
297 | |||
298 | |||
299 | 4.3: DOCUMENTATION | ||
300 | |||
301 | Documentation has often been more the exception than the rule with kernel | ||
302 | development. Even so, adequate documentation will help to ease the merging | ||
303 | of new code into the kernel, make life easier for other developers, and | ||
304 | will be helpful for your users. In many cases, the addition of | ||
305 | documentation has become essentially mandatory. | ||
306 | |||
307 | The first piece of documentation for any patch is its associated | ||
308 | changelog. Log entries should describe the problem being solved, the form | ||
309 | of the solution, the people who worked on the patch, any relevant | ||
310 | effects on performance, and anything else that might be needed to | ||
311 | understand the patch. | ||
312 | |||
313 | Any code which adds a new user-space interface - including new sysfs or | ||
314 | /proc files - should include documentation of that interface which enables | ||
315 | user-space developers to know what they are working with. See | ||
316 | Documentation/ABI/README for a description of how this documentation should | ||
317 | be formatted and what information needs to be provided. | ||
318 | |||
319 | The file Documentation/kernel-parameters.txt describes all of the kernel's | ||
320 | boot-time parameters. Any patch which adds new parameters should add the | ||
321 | appropriate entries to this file. | ||
322 | |||
323 | Any new configuration options must be accompanied by help text which | ||
324 | clearly explains the options and when the user might want to select them. | ||
325 | |||
326 | Internal API information for many subsystems is documented by way of | ||
327 | specially-formatted comments; these comments can be extracted and formatted | ||
328 | in a number of ways by the "kernel-doc" script. If you are working within | ||
329 | a subsystem which has kerneldoc comments, you should maintain them and add | ||
330 | them, as appropriate, for externally-available functions. Even in areas | ||
331 | which have not been so documented, there is no harm in adding kerneldoc | ||
332 | comments for the future; indeed, this can be a useful activity for | ||
333 | beginning kernel developers. The format of these comments, along with some | ||
334 | information on how to create kerneldoc templates can be found in the file | ||
335 | Documentation/kernel-doc-nano-HOWTO.txt. | ||
336 | |||
337 | Anybody who reads through a significant amount of existing kernel code will | ||
338 | note that, often, comments are most notable by their absence. Once again, | ||
339 | the expectations for new code are higher than they were in the past; | ||
340 | merging uncommented code will be harder. That said, there is little desire | ||
341 | for verbosely-commented code. The code should, itself, be readable, with | ||
342 | comments explaining the more subtle aspects. | ||
343 | |||
344 | Certain things should always be commented. Uses of memory barriers should | ||
345 | be accompanied by a line explaining why the barrier is necessary. The | ||
346 | locking rules for data structures generally need to be explained somewhere. | ||
347 | Major data structures need comprehensive documentation in general. | ||
348 | Non-obvious dependencies between separate bits of code should be pointed | ||
349 | out. 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 | |||
353 | 4.4: INTERNAL API CHANGES | ||
354 | |||
355 | The binary interface provided by the kernel to user space cannot be broken | ||
356 | except under the most severe circumstances. The kernel's internal | ||
357 | programming interfaces, instead, are highly fluid and can be changed when | ||
358 | the need arises. If you find yourself having to work around a kernel API, | ||
359 | or simply not using a specific functionality because it does not meet your | ||
360 | needs, that may be a sign that the API needs to change. As a kernel | ||
361 | developer, you are empowered to make such changes. | ||
362 | |||
363 | There are, of course, some catches. API changes can be made, but they need | ||
364 | to be well justified. So any patch making an internal API change should be | ||
365 | accompanied by a description of what the change is and why it is | ||
366 | necessary. This kind of change should also be broken out into a separate | ||
367 | patch, rather than buried within a larger patch. | ||
368 | |||
369 | The other catch is that a developer who changes an internal API is | ||
370 | generally charged with the task of fixing any code within the kernel tree | ||
371 | which is broken by the change. For a widely-used function, this duty can | ||
372 | lead to literally hundreds or thousands of changes - many of which are | ||
373 | likely to conflict with work being done by other developers. Needless to | ||
374 | say, this can be a large job, so it is best to be sure that the | ||
375 | justification is solid. | ||
376 | |||
377 | When making an incompatible API change, one should, whenever possible, | ||
378 | ensure that code which has not been updated is caught by the compiler. | ||
379 | This will help you to be sure that you have found all in-tree uses of that | ||
380 | interface. It will also alert developers of out-of-tree code that there is | ||
381 | a change that they need to respond to. Supporting out-of-tree code is not | ||
382 | something that kernel developers need to be worried about, but we also do | ||
383 | not have to make life harder for out-of-tree developers than it it needs to | ||
384 | be. | ||
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 @@ | |||
1 | 5: POSTING PATCHES | ||
2 | |||
3 | Sooner or later, the time comes when your work is ready to be presented to | ||
4 | the community for review and, eventually, inclusion into the mainline | ||
5 | kernel. Unsurprisingly, the kernel development community has evolved a set | ||
6 | of conventions and procedures which are used in the posting of patches; | ||
7 | following them will make life much easier for everybody involved. This | ||
8 | document will attempt to cover these expectations in reasonable detail; | ||
9 | more information can also be found in the files SubmittingPatches, | ||
10 | SubmittingDrivers, and SubmitChecklist in the kernel documentation | ||
11 | directory. | ||
12 | |||
13 | |||
14 | 5.1: WHEN TO POST | ||
15 | |||
16 | There is a constant temptation to avoid posting patches before they are | ||
17 | completely "ready." For simple patches, that is not a problem. If the | ||
18 | work being done is complex, though, there is a lot to be gained by getting | ||
19 | feedback from the community before the work is complete. So you should | ||
20 | consider posting in-progress work, or even making a git tree available so | ||
21 | that interested developers can catch up with your work at any time. | ||
22 | |||
23 | When posting code which is not yet considered ready for inclusion, it is a | ||
24 | good idea to say so in the posting itself. Also mention any major work | ||
25 | which remains to be done and any known problems. Fewer people will look at | ||
26 | patches which are known to be half-baked, but those who do will come in | ||
27 | with the idea that they can help you drive the work in the right direction. | ||
28 | |||
29 | |||
30 | 5.2: BEFORE CREATING PATCHES | ||
31 | |||
32 | There are a number of things which should be done before you consider | ||
33 | sending 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 | |||
51 | As a general rule, putting in some extra thought before posting code almost | ||
52 | always pays back the effort in short order. | ||
53 | |||
54 | |||
55 | 5.3: PATCH PREPARATION | ||
56 | |||
57 | The preparation of patches for posting can be a surprising amount of work, | ||
58 | but, once again, attempting to save time here is not generally advisable | ||
59 | even in the short term. | ||
60 | |||
61 | Patches must be prepared against a specific version of the kernel. As a | ||
62 | general rule, a patch should be based on the current mainline as found in | ||
63 | Linus's git tree. It may become necessary to make versions against -mm, | ||
64 | linux-next, or a subsystem tree, though, to facilitate wider testing and | ||
65 | review. Depending on the area of your patch and what is going on | ||
66 | elsewhere, basing a patch against these other trees can require a | ||
67 | significant amount of work resolving conflicts and dealing with API | ||
68 | changes. | ||
69 | |||
70 | Only the most simple changes should be formatted as a single patch; | ||
71 | everything else should be made as a logical series of changes. Splitting | ||
72 | up patches is a bit of an art; some developers spend a long time figuring | ||
73 | out how to do it in the way that the community expects. There are a few | ||
74 | rules 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 | |||
117 | Working to create the perfect patch series can be a frustrating process | ||
118 | which takes quite a bit of time and thought after the "real work" has been | ||
119 | done. When done properly, though, it is time well spent. | ||
120 | |||
121 | |||
122 | 5.4: PATCH FORMATTING | ||
123 | |||
124 | So now you have a perfect series of patches for posting, but the work is | ||
125 | not done quite yet. Each patch needs to be formatted into a message which | ||
126 | quickly and clearly communicates its purpose to the rest of the world. To | ||
127 | that 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 | |||
149 | The above three items should, normally, be the text used when committing | ||
150 | the 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 | |||
156 | You should avoid including changes to irrelevant files (those generated by | ||
157 | the build process, for example, or editor backup files) in the patch. The | ||
158 | file "dontdiff" in the Documentation directory can help in this regard; | ||
159 | pass it to diff with the "-X" option. | ||
160 | |||
161 | The tags mentioned above are used to describe how various developers have | ||
162 | been associated with the development of this patch. They are described in | ||
163 | detail in the SubmittingPatches document; what follows here is a brief | ||
164 | summary. Each of these lines has the format: | ||
165 | |||
166 | tag: Full Name <email address> optional-other-stuff | ||
167 | |||
168 | The 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 | |||
195 | Be careful in the addition of tags to your patches: only Cc: is appropriate | ||
196 | for addition without the explicit permission of the person named. | ||
197 | |||
198 | |||
199 | 5.5: SENDING THE PATCH | ||
200 | |||
201 | Before you mail your patches, there are a couple of other things you should | ||
202 | take 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 | |||
220 | Patches should always be sent as plain text. Please do not send them as | ||
221 | attachments; that makes it much harder for reviewers to quote sections of | ||
222 | the patch in their replies. Instead, just put the patch directly into your | ||
223 | message. | ||
224 | |||
225 | When mailing patches, it is important to send copies to anybody who might | ||
226 | be interested in it. Unlike some other projects, the kernel encourages | ||
227 | people to err on the side of sending too many copies; don't assume that the | ||
228 | relevant people will see your posting on the mailing lists. In particular, | ||
229 | copies 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 | |||
250 | When selecting recipients for a patch, it is good to have an idea of who | ||
251 | you think will eventually accept the patch and get it merged. While it | ||
252 | is possible to send patches directly to Linus Torvalds and have him merge | ||
253 | them, things are not normally done that way. Linus is busy, and there are | ||
254 | subsystem maintainers who watch over specific parts of the kernel. Usually | ||
255 | you will be wanting that maintainer to merge your patches. If there is no | ||
256 | obvious maintainer, Andrew Morton is often the patch target of last resort. | ||
257 | |||
258 | Patches need good subject lines. The canonical format for a patch line is | ||
259 | something like: | ||
260 | |||
261 | [PATCH nn/mm] subsys: one-line description of the patch | ||
262 | |||
263 | where "nn" is the ordinal number of the patch, "mm" is the total number of | ||
264 | patches in the series, and "subsys" is the name of the affected subsystem. | ||
265 | Clearly, nn/mm can be omitted for a single, standalone patch. | ||
266 | |||
267 | If you have a significant series of patches, it is customary to send an | ||
268 | introductory description as part zero. This convention is not universally | ||
269 | followed though; if you use it, remember that information in the | ||
270 | introduction does not make it into the kernel changelogs. So please ensure | ||
271 | that the patches, themselves, have complete changelog information. | ||
272 | |||
273 | In general, the second and following parts of a multi-part patch should be | ||
274 | sent as a reply to the first part so that they all thread together at the | ||
275 | receiving end. Tools like git and quilt have commands to mail out a set of | ||
276 | patches with the proper threading. If you have a long series, though, and | ||
277 | are using git, please provide the --no-chain-reply-to option to avoid | ||
278 | creating 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 @@ | |||
1 | 6: FOLLOWTHROUGH | ||
2 | |||
3 | At this point, you have followed the guidelines given so far and, with the | ||
4 | addition of your own engineering skills, have posted a perfect series of | ||
5 | patches. One of the biggest mistakes that even experienced kernel | ||
6 | developers can make is to conclude that their work is now done. In truth, | ||
7 | posting patches indicates a transition into the next stage of the process, | ||
8 | with, possibly, quite a bit of work yet to be done. | ||
9 | |||
10 | It is a rare patch which is so good at its first posting that there is no | ||
11 | room for improvement. The kernel development process recognizes this fact, | ||
12 | and, as a result, is heavily oriented toward the improvement of posted | ||
13 | code. You, as the author of that code, will be expected to work with the | ||
14 | kernel community to ensure that your code is up to the kernel's quality | ||
15 | standards. A failure to participate in this process is quite likely to | ||
16 | prevent the inclusion of your patches into the mainline. | ||
17 | |||
18 | |||
19 | 6.1: WORKING WITH REVIEWERS | ||
20 | |||
21 | A patch of any significance will result in a number of comments from other | ||
22 | developers as they review the code. Working with reviewers can be, for | ||
23 | many developers, the most intimidating part of the kernel development | ||
24 | process. Life can be made much easier, though, if you keep a few things in | ||
25 | mind: | ||
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 | |||
50 | What all of this comes down to is that, when reviewers send you comments, | ||
51 | you need to pay attention to the technical observations that they are | ||
52 | making. Do not let their form of expression or your own pride keep that | ||
53 | from happening. When you get review comments on a patch, take the time to | ||
54 | understand what the reviewer is trying to say. If possible, fix the things | ||
55 | that the reviewer is asking you to fix. And respond back to the reviewer: | ||
56 | thank them, and describe how you will answer their questions. | ||
57 | |||
58 | Note that you do not have to agree with every change suggested by | ||
59 | reviewers. If you believe that the reviewer has misunderstood your code, | ||
60 | explain what is really going on. If you have a technical objection to a | ||
61 | suggested change, describe it and justify your solution to the problem. If | ||
62 | your explanations make sense, the reviewer will accept them. Should your | ||
63 | explanation not prove persuasive, though, especially if others start to | ||
64 | agree with the reviewer, take some time to think things over again. It can | ||
65 | be easy to become blinded by your own solution to a problem to the point | ||
66 | that you don't realize that something is fundamentally wrong or, perhaps, | ||
67 | you're not even solving the right problem. | ||
68 | |||
69 | One fatal mistake is to ignore review comments in the hope that they will | ||
70 | go away. They will not go away. If you repost code without having | ||
71 | responded to the comments you got the time before, you're likely to find | ||
72 | that your patches go nowhere. | ||
73 | |||
74 | Speaking of reposting code: please bear in mind that reviewers are not | ||
75 | going to remember all the details of the code you posted the last time | ||
76 | around. So it is always a good idea to remind reviewers of previously | ||
77 | raised issues and how you dealt with them; the patch changelog is a good | ||
78 | place for this kind of information. Reviewers should not have to search | ||
79 | through list archives to familiarize themselves with what was said last | ||
80 | time; if you help them get a running start, they will be in a better mood | ||
81 | when they revisit your code. | ||
82 | |||
83 | What if you've tried to do everything right and things still aren't going | ||
84 | anywhere? Most technical disagreements can be resolved through discussion, | ||
85 | but there are times when somebody simply has to make a decision. If you | ||
86 | honestly believe that this decision is going against you wrongly, you can | ||
87 | always try appealing to a higher power. As of this writing, that higher | ||
88 | power tends to be Andrew Morton. Andrew has a great deal of respect in the | ||
89 | kernel development community; he can often unjam a situation which seems to | ||
90 | be hopelessly blocked. Appealing to Andrew should not be done lightly, | ||
91 | though, and not before all other alternatives have been explored. And bear | ||
92 | in mind, of course, that he may not agree with you either. | ||
93 | |||
94 | |||
95 | 6.2: WHAT HAPPENS NEXT | ||
96 | |||
97 | If a patch is considered to be a good thing to add to the kernel, and once | ||
98 | most of the review issues have been resolved, the next step is usually | ||
99 | entry into a subsystem maintainer's tree. How that works varies from one | ||
100 | subsystem to the next; each maintainer has his or her own way of doing | ||
101 | things. In particular, there may be more than one tree - one, perhaps, | ||
102 | dedicated to patches planned for the next merge window, and another for | ||
103 | longer-term work. | ||
104 | |||
105 | For patches applying to areas for which there is no obvious subsystem tree | ||
106 | (memory management patches, for example), the default tree often ends up | ||
107 | being -mm. Patches which affect multiple subsystems can also end up going | ||
108 | through the -mm tree. | ||
109 | |||
110 | Inclusion into a subsystem tree can bring a higher level of visibility to a | ||
111 | patch. Now other developers working with that tree will get the patch by | ||
112 | default. Subsystem trees typically feed into -mm and linux-next as well, | ||
113 | making their contents visible to the development community as a whole. At | ||
114 | this point, there's a good chance that you will get more comments from a | ||
115 | new set of reviewers; these comments need to be answered as in the previous | ||
116 | round. | ||
117 | |||
118 | What may also happen at this point, depending on the nature of your patch, | ||
119 | is that conflicts with work being done by others turn up. In the worst | ||
120 | case, heavy patch conflicts can result in some work being put on the back | ||
121 | burner so that the remaining patches can be worked into shape and merged. | ||
122 | Other times, conflict resolution will involve working with the other | ||
123 | developers and, possibly, moving some patches between trees to ensure that | ||
124 | everything applies cleanly. This work can be a pain, but count your | ||
125 | blessings: before the advent of the linux-next tree, these conflicts often | ||
126 | only turned up during the merge window and had to be addressed in a hurry. | ||
127 | Now they can be resolved at leisure, before the merge window opens. | ||
128 | |||
129 | Some day, if all goes well, you'll log on and see that your patch has been | ||
130 | merged into the mainline kernel. Congratulations! Once the celebration is | ||
131 | complete (and you have added yourself to the MAINTAINERS file), though, it | ||
132 | is worth remembering an important little fact: the job still is not done. | ||
133 | Merging into the mainline brings its own challenges. | ||
134 | |||
135 | To begin with, the visibility of your patch has increased yet again. There | ||
136 | may be a new round of comments from developers who had not been aware of | ||
137 | the patch before. It may be tempting to ignore them, since there is no | ||
138 | longer any question of your code being merged. Resist that temptation, | ||
139 | though; you still need to be responsive to developers who have questions or | ||
140 | suggestions. | ||
141 | |||
142 | More importantly, though: inclusion into the mainline puts your code into | ||
143 | the hands of a much larger group of testers. Even if you have contributed | ||
144 | a driver for hardware which is not yet available, you will be surprised by | ||
145 | how many people will build your code into their kernels. And, of course, | ||
146 | where there are testers, there will be bug reports. | ||
147 | |||
148 | The worst sort of bug reports are regressions. If your patch causes a | ||
149 | regression, you'll find an uncomfortable number of eyes upon you; | ||
150 | regressions need to be fixed as soon as possible. If you are unwilling or | ||
151 | unable to fix the regression (and nobody else does it for you), your patch | ||
152 | will almost certainly be removed during the stabilization period. Beyond | ||
153 | negating all of the work you have done to get your patch into the mainline, | ||
154 | having a patch pulled as the result of a failure to fix a regression could | ||
155 | well make it harder for you to get work merged in the future. | ||
156 | |||
157 | After any regressions have been dealt with, there may be other, ordinary | ||
158 | bugs to deal with. The stabilization period is your best opportunity to | ||
159 | fix these bugs and ensure that your code's debut in a mainline kernel | ||
160 | release is as solid as possible. So, please, answer bug reports, and fix | ||
161 | the problems if at all possible. That's what the stabilization period is | ||
162 | for; you can start creating cool new patches once any problems with the old | ||
163 | ones have been taken care of. | ||
164 | |||
165 | And don't forget that there are other milestones which may also create bug | ||
166 | reports: the next mainline stable release, when prominent distributors pick | ||
167 | up a version of the kernel containing your patch, etc. Continuing to | ||
168 | respond to these reports is a matter of basic pride in your work. If that | ||
169 | is insufficient motivation, though, it's also worth considering that the | ||
170 | development community remembers developers who lose interest in their code | ||
171 | after it's merged. The next time you post a patch, they will be evaluating | ||
172 | it with the assumption that you will not be around to maintain it | ||
173 | afterward. | ||
174 | |||
175 | |||
176 | 6.3: OTHER THINGS THAT CAN HAPPEN | ||
177 | |||
178 | One day, you may open your mail client and see that somebody has mailed you | ||
179 | a patch to your code. That is one of the advantages of having your code | ||
180 | out there in the open, after all. If you agree with the patch, you can | ||
181 | either forward it on to the subsystem maintainer (be sure to include a | ||
182 | proper From: line so that the attribution is correct, and add a signoff of | ||
183 | your own), or send an Acked-by: response back and let the original poster | ||
184 | send it upward. | ||
185 | |||
186 | If you disagree with the patch, send a polite response explaining why. If | ||
187 | possible, tell the author what changes need to be made to make the patch | ||
188 | acceptable to you. There is a certain resistance to merging patches which | ||
189 | are opposed by the author and maintainer of the code, but it only goes so | ||
190 | far. If you are seen as needlessly blocking good work, those patches will | ||
191 | eventually flow around you and get into the mainline anyway. In the Linux | ||
192 | kernel, nobody has absolute veto power over any code. Except maybe Linus. | ||
193 | |||
194 | On very rare occasion, you may see something completely different: another | ||
195 | developer posts a different solution to your problem. At that point, | ||
196 | chances are that one of the two patches will not be merged, and "mine was | ||
197 | here first" is not considered to be a compelling technical argument. If | ||
198 | somebody else's patch displaces yours and gets into the mainline, there is | ||
199 | really only one way to respond: be pleased that your problem got solved and | ||
200 | get on with your work. Having one's work shoved aside in this manner can | ||
201 | be hurtful and discouraging, but the community will remember your reaction | ||
202 | long 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 @@ | |||
1 | 7: ADVANCED TOPICS | ||
2 | |||
3 | At this point, hopefully, you have a handle on how the development process | ||
4 | works. There is still more to learn, however! This section will cover a | ||
5 | number of topics which can be helpful for developers wanting to become a | ||
6 | regular part of the Linux kernel development process. | ||
7 | |||
8 | 7.1: MANAGING PATCHES WITH GIT | ||
9 | |||
10 | The use of distributed version control for the kernel began in early 2002, | ||
11 | when Linus first started playing with the proprietary BitKeeper | ||
12 | application. While BitKeeper was controversial, the approach to software | ||
13 | version management it embodied most certainly was not. Distributed version | ||
14 | control enabled an immediate acceleration of the kernel development | ||
15 | project. In current times, there are several free alternatives to | ||
16 | BitKeeper. For better or for worse, the kernel project has settled on git | ||
17 | as its tool of choice. | ||
18 | |||
19 | Managing patches with git can make life much easier for the developer, | ||
20 | especially as the volume of those patches grows. Git also has its rough | ||
21 | edges and poses certain hazards; it is a young and powerful tool which is | ||
22 | still being civilized by its developers. This document will not attempt to | ||
23 | teach the reader how to use git; that would be sufficient material for a | ||
24 | long document in its own right. Instead, the focus here will be on how git | ||
25 | fits into the kernel development process in particular. Developers who | ||
26 | wish 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 | |||
32 | and on various tutorials found on the web. | ||
33 | |||
34 | The first order of business is to read the above sites and get a solid | ||
35 | understanding of how git works before trying to use it to make patches | ||
36 | available to others. A git-using developer should be able to obtain a copy | ||
37 | of the mainline repository, explore the revision history, commit changes to | ||
38 | the tree, use branches, etc. An understanding of git's tools for the | ||
39 | rewriting of history (such as rebase) is also useful. Git comes with its | ||
40 | own terminology and concepts; a new user of git should know about refs, | ||
41 | remote branches, the index, fast-forward merges, pushes and pulls, detached | ||
42 | heads, etc. It can all be a little intimidating at the outset, but the | ||
43 | concepts are not that hard to grasp with a bit of study. | ||
44 | |||
45 | Using git to generate patches for submission by email can be a good | ||
46 | exercise while coming up to speed. | ||
47 | |||
48 | When you are ready to start putting up git trees for others to look at, you | ||
49 | will, of course, need a server that can be pulled from. Setting up such a | ||
50 | server with git-daemon is relatively straightforward if you have a system | ||
51 | which is accessible to the Internet. Otherwise, free, public hosting sites | ||
52 | (Github, for example) are starting to appear on the net. Established | ||
53 | developers can get an account on kernel.org, but those are not easy to come | ||
54 | by; see http://kernel.org/faq/ for more information. | ||
55 | |||
56 | The normal git workflow involves the use of a lot of branches. Each line | ||
57 | of development can be separated into a separate "topic branch" and | ||
58 | maintained independently. Branches in git are cheap, there is no reason to | ||
59 | not make free use of them. And, in any case, you should not do your | ||
60 | development in any branch which you intend to ask others to pull from. | ||
61 | Publicly-available branches should be created with care; merge in patches | ||
62 | from development branches when they are in complete form and ready to go - | ||
63 | not before. | ||
64 | |||
65 | Git provides some powerful tools which can allow you to rewrite your | ||
66 | development history. An inconvenient patch (one which breaks bisection, | ||
67 | say, or which has some other sort of obvious bug) can be fixed in place or | ||
68 | made to disappear from the history entirely. A patch series can be | ||
69 | rewritten as if it had been written on top of today's mainline, even though | ||
70 | you have been working on it for months. Changes can be transparently | ||
71 | shifted from one branch to another. And so on. Judicious use of git's | ||
72 | ability to revise history can help in the creation of clean patch sets with | ||
73 | fewer problems. | ||
74 | |||
75 | Excessive use of this capability can lead to other problems, though, beyond | ||
76 | a simple obsession for the creation of the perfect project history. | ||
77 | Rewriting history will rewrite the changes contained in that history, | ||
78 | turning a tested (hopefully) kernel tree into an untested one. But, beyond | ||
79 | that, developers cannot easily collaborate if they do not have a shared | ||
80 | view of the project history; if you rewrite history which other developers | ||
81 | have pulled into their repositories, you will make life much more difficult | ||
82 | for those developers. So a simple rule of thumb applies here: history | ||
83 | which has been exported to others should generally be seen as immutable | ||
84 | thereafter. | ||
85 | |||
86 | So, once you push a set of changes to your publicly-available server, those | ||
87 | changes should not be rewritten. Git will attempt to enforce this rule if | ||
88 | you 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 | ||
90 | override this check, and there may be times when it is necessary to rewrite | ||
91 | an exported tree. Moving changesets between trees to avoid conflicts in | ||
92 | linux-next is one example. But such actions should be rare. This is one | ||
93 | of the reasons why development should be done in private branches (which | ||
94 | can be rewritten if necessary) and only moved into public branches when | ||
95 | it's in a reasonably advanced state. | ||
96 | |||
97 | As the mainline (or other tree upon which a set of changes is based) | ||
98 | advances, it is tempting to merge with that tree to stay on the leading | ||
99 | edge. For a private branch, rebasing can be an easy way to keep up with | ||
100 | another tree, but rebasing is not an option once a tree is exported to the | ||
101 | world. Once that happens, a full merge must be done. Merging occasionally | ||
102 | makes good sense, but overly frequent merges can clutter the history | ||
103 | needlessly. Suggested technique in this case is to merge infrequently, and | ||
104 | generally only at specific release points (such as a mainline -rc | ||
105 | release). If you are nervous about specific changes, you can always | ||
106 | perform test merges in a private branch. The git "rerere" tool can be | ||
107 | useful in such situations; it remembers how merge conflicts were resolved | ||
108 | so that you don't have to do the same work twice. | ||
109 | |||
110 | One of the biggest recurring complaints about tools like git is this: the | ||
111 | mass movement of patches from one repository to another makes it easy to | ||
112 | slip in ill-advised changes which go into the mainline below the review | ||
113 | radar. Kernel developers tend to get unhappy when they see that kind of | ||
114 | thing happening; putting up a git tree with unreviewed or off-topic patches | ||
115 | can 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 | |||
124 | To avoid this kind of situation, ensure that all patches within a given | ||
125 | branch stick closely to the associated topic; a "driver fixes" branch | ||
126 | should not be making changes to the core memory management code. And, most | ||
127 | importantly, do not use a git tree to bypass the review process. Post an | ||
128 | occasional summary of the tree to the relevant list, and, when the time is | ||
129 | right, request that the tree be included in linux-next. | ||
130 | |||
131 | If and when others start to send patches for inclusion into your tree, | ||
132 | don't forget to review them. Also ensure that you maintain the correct | ||
133 | authorship information; the git "am" tool does its best in this regard, but | ||
134 | you may have to add a "From:" line to the patch if it has been relayed to | ||
135 | you via a third party. | ||
136 | |||
137 | When requesting a pull, be sure to give all the relevant information: where | ||
138 | your tree is, what branch to pull, and what changes will result from the | ||
139 | pull. The git request-pull command can be helpful in this regard; it will | ||
140 | format the request as other developers expect, and will also check to be | ||
141 | sure that you have remembered to push those changes to the public server. | ||
142 | |||
143 | |||
144 | 7.2: REVIEWING PATCHES | ||
145 | |||
146 | Some readers will certainly object to putting this section with "advanced | ||
147 | topics" on the grounds that even beginning kernel developers should be | ||
148 | reviewing patches. It is certainly true that there is no better way to | ||
149 | learn how to program in the kernel environment than by looking at code | ||
150 | posted by others. In addition, reviewers are forever in short supply; by | ||
151 | looking at code you can make a significant contribution to the process as a | ||
152 | whole. | ||
153 | |||
154 | Reviewing code can be an intimidating prospect, especially for a new kernel | ||
155 | developer who may well feel nervous about questioning code - in public - | ||
156 | which has been posted by those with more experience. Even code written by | ||
157 | the most experienced developers can be improved, though. Perhaps the best | ||
158 | piece of advice for reviewers (all reviewers) is this: phrase review | ||
159 | comments as questions rather than criticisms. Asking "how does the lock | ||
160 | get released in this path?" will always work better than stating "the | ||
161 | locking here is wrong." | ||
162 | |||
163 | Different developers will review code from different points of view. Some | ||
164 | are mostly concerned with coding style and whether code lines have trailing | ||
165 | white space. Others will focus primarily on whether the change implemented | ||
166 | by the patch as a whole is a good thing for the kernel or not. Yet others | ||
167 | will check for problematic locking, excessive stack usage, possible | ||
168 | security issues, duplication of code found elsewhere, adequate | ||
169 | documentation, adverse effects on performance, user-space ABI changes, etc. | ||
170 | All types of review, if they lead to better code going into the kernel, are | ||
171 | welcome 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 @@ | |||
1 | 8: FOR MORE INFORMATION | ||
2 | |||
3 | There are numerous sources of information on Linux kernel development and | ||
4 | related topics. First among those will always be the Documentation | ||
5 | directory found in the kernel source distribution. The top-level HOWTO | ||
6 | file is an important starting point; SubmittingPatches and | ||
7 | SubmittingDrivers are also something which all kernel developers should | ||
8 | read. Many internal kernel APIs are documented using the kerneldoc | ||
9 | mechanism; "make htmldocs" or "make pdfdocs" can be used to generate those | ||
10 | documents in HTML or PDF format (though the version of TeX shipped by some | ||
11 | distributions runs into internal limits and fails to process the documents | ||
12 | properly). | ||
13 | |||
14 | Various web sites discuss kernel development at all levels of detail. Your | ||
15 | author would like to humbly suggest http://lwn.net/ as a source; | ||
16 | information on many specific kernel topics can be found via the LWN kernel | ||
17 | index at: | ||
18 | |||
19 | http://lwn.net/Kernel/Index/ | ||
20 | |||
21 | Beyond that, a valuable resource for kernel developers is: | ||
22 | |||
23 | http://kernelnewbies.org/ | ||
24 | |||
25 | Information about the linux-next tree gathers at: | ||
26 | |||
27 | http://linux.f-seidel.de/linux-next/pmwiki/ | ||
28 | |||
29 | And, of course, one should not forget http://kernel.org/, the definitive | ||
30 | location for kernel release information. | ||
31 | |||
32 | There 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 | |||
42 | All of these books suffer from a common fault, though: they tend to be | ||
43 | somewhat obsolete by the time they hit the shelves, and they have been on | ||
44 | the shelves for a while now. Still, there is quite a bit of good | ||
45 | information to be found there. | ||
46 | |||
47 | Documentation 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 | |||
54 | 9: CONCLUSION | ||
55 | |||
56 | Congratulations to anybody who has made it through this long-winded | ||
57 | document. Hopefully it has provided a helpful understanding of how the | ||
58 | Linux kernel is developed and how you can participate in that process. | ||
59 | |||
60 | In the end, it's the participation that matters. Any open source software | ||
61 | project is no more than the sum of what its contributors put into it. The | ||
62 | Linux kernel has progressed as quickly and as well as it has because it has | ||
63 | been helped by an impressively large group of developers, all of whom are | ||
64 | working to make it better. The kernel is a premier example of what can be | ||
65 | done when thousands of people work together toward a common goal. | ||
66 | |||
67 | The kernel can always benefit from a larger developer base, though. There | ||
68 | is always more work to do. But, just as importantly, most other | ||
69 | participants in the Linux ecosystem can benefit through contributing to the | ||
70 | kernel. Getting code into the mainline is the key to higher code quality, | ||
71 | lower maintenance and distribution costs, a higher level of influence over | ||
72 | the direction of kernel development, and more. It is a situation where | ||
73 | everybody involved wins. Fire up your editor and come join us; you will be | ||
74 | more 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 |
50 | 53c700_d.h | 49 | 53c700_d.h |
51 | 53c8xx_d.h* | ||
52 | COPYING | ||
53 | CREDITS | ||
54 | CVS | 50 | CVS |
55 | ChangeSet | 51 | ChangeSet |
56 | Image | 52 | Image |
57 | Kerntypes | 53 | Kerntypes |
58 | MODS.txt | 54 | Module.markers |
59 | Module.symvers | 55 | Module.symvers |
60 | PENDING | 56 | PENDING |
61 | SCCS | 57 | SCCS |
@@ -73,7 +69,9 @@ autoconf.h* | |||
73 | bbootsect | 69 | bbootsect |
74 | bin2c | 70 | bin2c |
75 | binkernel.spec | 71 | binkernel.spec |
72 | binoffset | ||
76 | bootsect | 73 | bootsect |
74 | bounds.h | ||
77 | bsetup | 75 | bsetup |
78 | btfixupprep | 76 | btfixupprep |
79 | build | 77 | build |
@@ -89,39 +87,36 @@ config_data.h* | |||
89 | config_data.gz* | 87 | config_data.gz* |
90 | conmakehash | 88 | conmakehash |
91 | consolemap_deftbl.c* | 89 | consolemap_deftbl.c* |
90 | cpustr.h | ||
92 | crc32table.h* | 91 | crc32table.h* |
93 | cscope.* | 92 | cscope.* |
94 | defkeymap.c* | 93 | defkeymap.c |
95 | devlist.h* | 94 | devlist.h* |
96 | docproc | 95 | docproc |
97 | dummy_sym.c* | ||
98 | elf2ecoff | 96 | elf2ecoff |
99 | elfconfig.h* | 97 | elfconfig.h* |
100 | filelist | ||
101 | fixdep | 98 | fixdep |
102 | fore200e_mkfirm | 99 | fore200e_mkfirm |
103 | fore200e_pca_fw.c* | 100 | fore200e_pca_fw.c* |
104 | gconf | 101 | gconf |
105 | gen-devlist | 102 | gen-devlist |
106 | gen-kdb_cmds.c* | ||
107 | gen_crc32table | 103 | gen_crc32table |
108 | gen_init_cpio | 104 | gen_init_cpio |
109 | genksyms | 105 | genksyms |
110 | gentbl | ||
111 | *_gray256.c | 106 | *_gray256.c |
107 | ihex2fw | ||
112 | ikconfig.h* | 108 | ikconfig.h* |
113 | initramfs_data.cpio | 109 | initramfs_data.cpio |
114 | initramfs_data.cpio.gz | 110 | initramfs_data.cpio.gz |
115 | initramfs_list | 111 | initramfs_list |
116 | kallsyms | 112 | kallsyms |
117 | kconfig | 113 | kconfig |
118 | kconfig.tk | 114 | keywords.c |
119 | keywords.c* | ||
120 | ksym.c* | 115 | ksym.c* |
121 | ksym.h* | 116 | ksym.h* |
122 | kxgettext | 117 | kxgettext |
123 | lkc_defs.h | 118 | lkc_defs.h |
124 | lex.c* | 119 | lex.c |
125 | lex.*.c | 120 | lex.*.c |
126 | logo_*.c | 121 | logo_*.c |
127 | logo_*_clut224.c | 122 | logo_*_clut224.c |
@@ -130,7 +125,6 @@ lxdialog | |||
130 | mach-types | 125 | mach-types |
131 | mach-types.h | 126 | mach-types.h |
132 | machtypes.h | 127 | machtypes.h |
133 | make_times_h | ||
134 | map | 128 | map |
135 | maui_boot.h | 129 | maui_boot.h |
136 | mconf | 130 | mconf |
@@ -138,6 +132,7 @@ miboot* | |||
138 | mk_elfconfig | 132 | mk_elfconfig |
139 | mkboot | 133 | mkboot |
140 | mkbugboot | 134 | mkbugboot |
135 | mkcpustr | ||
141 | mkdep | 136 | mkdep |
142 | mkprep | 137 | mkprep |
143 | mktables | 138 | mktables |
@@ -145,11 +140,12 @@ mktree | |||
145 | modpost | 140 | modpost |
146 | modules.order | 141 | modules.order |
147 | modversions.h* | 142 | modversions.h* |
143 | ncscope.* | ||
148 | offset.h | 144 | offset.h |
149 | offsets.h | 145 | offsets.h |
150 | oui.c* | 146 | oui.c* |
151 | parse.c* | 147 | parse.c |
152 | parse.h* | 148 | parse.h |
153 | patches* | 149 | patches* |
154 | pca200e.bin | 150 | pca200e.bin |
155 | pca200e_ecd.bin2 | 151 | pca200e_ecd.bin2 |
@@ -157,7 +153,7 @@ piggy.gz | |||
157 | piggyback | 153 | piggyback |
158 | pnmtologo | 154 | pnmtologo |
159 | ppc_defs.h* | 155 | ppc_defs.h* |
160 | promcon_tbl.c* | 156 | promcon_tbl.c |
161 | pss_boot.h | 157 | pss_boot.h |
162 | qconf | 158 | qconf |
163 | raid6altivec*.c | 159 | raid6altivec*.c |
@@ -168,27 +164,38 @@ series | |||
168 | setup | 164 | setup |
169 | setup.bin | 165 | setup.bin |
170 | setup.elf | 166 | setup.elf |
171 | sim710_d.h* | ||
172 | sImage | 167 | sImage |
173 | sm_tbl* | 168 | sm_tbl* |
174 | split-include | 169 | split-include |
170 | syscalltab.h | ||
175 | tags | 171 | tags |
176 | tftpboot.img | 172 | tftpboot.img |
177 | timeconst.h | 173 | timeconst.h |
178 | times.h* | 174 | times.h* |
179 | tkparse | ||
180 | trix_boot.h | 175 | trix_boot.h |
181 | utsrelease.h* | 176 | utsrelease.h* |
177 | vdso-syms.lds | ||
182 | vdso.lds | 178 | vdso.lds |
179 | vdso32-int80-syms.lds | ||
180 | vdso32-syms.lds | ||
181 | vdso32-syscall-syms.lds | ||
182 | vdso32-sysenter-syms.lds | ||
183 | vdso32.lds | ||
184 | vdso32.so.dbg | ||
185 | vdso64.lds | ||
186 | vdso64.so.dbg | ||
183 | version.h* | 187 | version.h* |
184 | vmlinux | 188 | vmlinux |
185 | vmlinux-* | 189 | vmlinux-* |
186 | vmlinux.aout | 190 | vmlinux.aout |
187 | vmlinux*.lds* | 191 | vmlinux.lds |
188 | vmlinux*.scr | ||
189 | vsyscall.lds | 192 | vsyscall.lds |
193 | vsyscall_32.lds | ||
190 | wanxlfw.inc | 194 | wanxlfw.inc |
191 | uImage | 195 | uImage |
192 | unifdef | 196 | unifdef |
197 | wakeup.bin | ||
198 | wakeup.elf | ||
199 | wakeup.lds | ||
193 | zImage* | 200 | zImage* |
194 | zconf.hash.c | 201 | zconf.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 | ||
57 | Accepted options: | 57 | Accepted 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 | ||
110 | vbemode:x | 110 | vbemode: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 | |||
28 | mode "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 | |||
171 | Notes: | ||
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 | ||
9 | What: old static regulatory information and ieee80211_regdom module parameter | ||
10 | When: 2.6.29 | ||
11 | Why: 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. | ||
23 | Who: Luis R. Rodriguez <lrodriguez@atheros.com> | ||
24 | |||
25 | --------------------------- | ||
26 | |||
9 | What: dev->power.power_state | 27 | What: dev->power.power_state |
10 | When: July 2007 | 28 | When: July 2007 |
11 | Why: Broken design for runtime control over driver power states, confusing | 29 | Why: 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 | |||
235 | When: January 2009 or Linux 2.7.0, whichever comes first | 256 | When: January 2009 or Linux 2.7.0, whichever comes first |
236 | Why: Superseded by newer revisions or modules | 257 | Why: Superseded by newer revisions or modules |
237 | Who: Jan Engelhardt <jengelh@computergmbh.de> | 258 | Who: Jan Engelhardt <jengelh@computergmbh.de> |
@@ -266,11 +287,19 @@ Who: Glauber Costa <gcosta@redhat.com> | |||
266 | 287 | ||
267 | --------------------------- | 288 | --------------------------- |
268 | 289 | ||
269 | What: old style serial driver for ColdFire (CONFIG_SERIAL_COLDFIRE) | 290 | What: remove HID compat support |
270 | When: 2.6.28 | 291 | When: 2.6.29 |
271 | Why: This driver still uses the old interface and has been replaced | 292 | Why: needed only as a temporary solution until distros fix themselves up |
272 | by CONFIG_SERIAL_MCF. | 293 | Who: Jiri Slaby <jirislaby@gmail.com> |
273 | Who: Sebastian Siewior <sebastian@breakpoint.cc> | 294 | |
295 | --------------------------- | ||
296 | |||
297 | What: print_fn_descriptor_symbol() | ||
298 | When: October 2009 | ||
299 | Why: 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. | ||
302 | Who: 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 | |||
2 | Miscellaneous Device control operations for the autofs4 kernel module | ||
3 | ==================================================================== | ||
4 | |||
5 | The problem | ||
6 | =========== | ||
7 | |||
8 | There is a problem with active restarts in autofs (that is to say | ||
9 | restarting autofs when there are busy mounts). | ||
10 | |||
11 | During normal operation autofs uses a file descriptor opened on the | ||
12 | directory that is being managed in order to be able to issue control | ||
13 | operations. Using a file descriptor gives ioctl operations access to | ||
14 | autofs specific information stored in the super block. The operations | ||
15 | are things such as setting an autofs mount catatonic, setting the | ||
16 | expire timeout and requesting expire checks. As is explained below, | ||
17 | certain types of autofs triggered mounts can end up covering an autofs | ||
18 | mount itself which prevents us being able to use open(2) to obtain a | ||
19 | file descriptor for these operations if we don't already have one open. | ||
20 | |||
21 | Currently autofs uses "umount -l" (lazy umount) to clear active mounts | ||
22 | at restart. While using lazy umount works for most cases, anything that | ||
23 | needs to walk back up the mount tree to construct a path, such as | ||
24 | getcwd(2) and the proc file system /proc/<pid>/cwd, no longer works | ||
25 | because the point from which the path is constructed has been detached | ||
26 | from the mount tree. | ||
27 | |||
28 | The actual problem with autofs is that it can't reconnect to existing | ||
29 | mounts. Immediately one thinks of just adding the ability to remount | ||
30 | autofs file systems would solve it, but alas, that can't work. This is | ||
31 | because autofs direct mounts and the implementation of "on demand mount | ||
32 | and expire" of nested mount trees have the file system mounted directly | ||
33 | on top of the mount trigger directory dentry. | ||
34 | |||
35 | For example, there are two types of automount maps, direct (in the kernel | ||
36 | module source you will see a third type called an offset, which is just | ||
37 | a direct mount in disguise) and indirect. | ||
38 | |||
39 | Here is a master map with direct and indirect map entries: | ||
40 | |||
41 | /- /etc/auto.direct | ||
42 | /test /etc/auto.indirect | ||
43 | |||
44 | and the corresponding map files: | ||
45 | |||
46 | /etc/auto.direct: | ||
47 | |||
48 | /automount/dparse/g6 budgie:/autofs/export1 | ||
49 | /automount/dparse/g1 shark:/autofs/export1 | ||
50 | and so on. | ||
51 | |||
52 | /etc/auto.indirect: | ||
53 | |||
54 | g1 shark:/autofs/export1 | ||
55 | g6 budgie:/autofs/export1 | ||
56 | and so on. | ||
57 | |||
58 | For the above indirect map an autofs file system is mounted on /test and | ||
59 | mounts are triggered for each sub-directory key by the inode lookup | ||
60 | operation. So we see a mount of shark:/autofs/export1 on /test/g1, for | ||
61 | example. | ||
62 | |||
63 | The way that direct mounts are handled is by making an autofs mount on | ||
64 | each full path, such as /automount/dparse/g1, and using it as a mount | ||
65 | trigger. So when we walk on the path we mount shark:/autofs/export1 "on | ||
66 | top of this mount point". Since these are always directories we can | ||
67 | use the follow_link inode operation to trigger the mount. | ||
68 | |||
69 | But, each entry in direct and indirect maps can have offsets (making | ||
70 | them multi-mount map entries). | ||
71 | |||
72 | For example, an indirect mount map entry could also be: | ||
73 | |||
74 | g1 \ | ||
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 | |||
81 | and 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 | |||
90 | One of the issues with version 4 of autofs was that, when mounting an | ||
91 | entry with a large number of offsets, possibly with nesting, we needed | ||
92 | to mount and umount all of the offsets as a single unit. Not really a | ||
93 | problem, except for people with a large number of offsets in map entries. | ||
94 | This mechanism is used for the well known "hosts" map and we have seen | ||
95 | cases (in 2.4) where the available number of mounts are exhausted or | ||
96 | where the number of privileged ports available is exhausted. | ||
97 | |||
98 | In version 5 we mount only as we go down the tree of offsets and | ||
99 | similarly for expiring them which resolves the above problem. There is | ||
100 | somewhat more detail to the implementation but it isn't needed for the | ||
101 | sake of the problem explanation. The one important detail is that these | ||
102 | offsets are implemented using the same mechanism as the direct mounts | ||
103 | above and so the mount points can be covered by a mount. | ||
104 | |||
105 | The current autofs implementation uses an ioctl file descriptor opened | ||
106 | on the mount point for control operations. The references held by the | ||
107 | descriptor are accounted for in checks made to determine if a mount is | ||
108 | in use and is also used to access autofs file system information held | ||
109 | in the mount super block. So the use of a file handle needs to be | ||
110 | retained. | ||
111 | |||
112 | |||
113 | The Solution | ||
114 | ============ | ||
115 | |||
116 | To be able to restart autofs leaving existing direct, indirect and | ||
117 | offset mounts in place we need to be able to obtain a file handle | ||
118 | for these potentially covered autofs mount points. Rather than just | ||
119 | implement an isolated operation it was decided to re-implement the | ||
120 | existing ioctl interface and add new operations to provide this | ||
121 | functionality. | ||
122 | |||
123 | In addition, to be able to reconstruct a mount tree that has busy mounts, | ||
124 | the uid and gid of the last user that triggered the mount needs to be | ||
125 | available because these can be used as macro substitution variables in | ||
126 | autofs maps. They are recorded at mount request time and an operation | ||
127 | has been added to retrieve them. | ||
128 | |||
129 | Since we're re-implementing the control interface, a couple of other | ||
130 | problems with the existing interface have been addressed. First, when | ||
131 | a mount or expire operation completes a status is returned to the | ||
132 | kernel by either a "send ready" or a "send fail" operation. The | ||
133 | "send fail" operation of the ioctl interface could only ever send | ||
134 | ENOENT so the re-implementation allows user space to send an actual | ||
135 | status. Another expensive operation in user space, for those using | ||
136 | very large maps, is discovering if a mount is present. Usually this | ||
137 | involves scanning /proc/mounts and since it needs to be done quite | ||
138 | often it can introduce significant overhead when there are many entries | ||
139 | in the mount table. An operation to lookup the mount status of a mount | ||
140 | point dentry (covered or not) has also been added. | ||
141 | |||
142 | Current kernel development policy recommends avoiding the use of the | ||
143 | ioctl mechanism in favor of systems such as Netlink. An implementation | ||
144 | using this system was attempted to evaluate its suitability and it was | ||
145 | found to be inadequate, in this case. The Generic Netlink system was | ||
146 | used for this as raw Netlink would lead to a significant increase in | ||
147 | complexity. There's no question that the Generic Netlink system is an | ||
148 | elegant solution for common case ioctl functions but it's not a complete | ||
149 | replacement probably because it's primary purpose in life is to be a | ||
150 | message bus implementation rather than specifically an ioctl replacement. | ||
151 | While it would be possible to work around this there is one concern | ||
152 | that lead to the decision to not use it. This is that the autofs | ||
153 | expire in the daemon has become far to complex because umount | ||
154 | candidates are enumerated, almost for no other reason than to "count" | ||
155 | the number of times to call the expire ioctl. This involves scanning | ||
156 | the mount table which has proved to be a big overhead for users with | ||
157 | large maps. The best way to improve this is try and get back to the | ||
158 | way the expire was done long ago. That is, when an expire request is | ||
159 | issued for a mount (file handle) we should continually call back to | ||
160 | the daemon until we can't umount any more mounts, then return the | ||
161 | appropriate status to the daemon. At the moment we just expire one | ||
162 | mount at a time. A Generic Netlink implementation would exclude this | ||
163 | possibility for future development due to the requirements of the | ||
164 | message bus architecture. | ||
165 | |||
166 | |||
167 | autofs4 Miscellaneous Device mount control interface | ||
168 | ==================================================== | ||
169 | |||
170 | The control interface is opening a device node, typically /dev/autofs. | ||
171 | |||
172 | All the ioctls use a common structure to pass the needed parameter | ||
173 | information and return operation results: | ||
174 | |||
175 | struct 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 | |||
188 | The ioctlfd field is a mount point file descriptor of an autofs mount | ||
189 | point. It is returned by the open call and is used by all calls except | ||
190 | the check for whether a given path is a mount point, where it may | ||
191 | optionally be used to check a specific mount corresponding to a given | ||
192 | mount point file descriptor, and when requesting the uid and gid of the | ||
193 | last successful mount on a directory within the autofs file system. | ||
194 | |||
195 | The fields arg1 and arg2 are used to communicate parameters and results of | ||
196 | calls made as described below. | ||
197 | |||
198 | The path field is used to pass a path where it is needed and the size field | ||
199 | is used account for the increased structure length when translating the | ||
200 | structure sent from user space. | ||
201 | |||
202 | This structure can be initialized before setting specific fields by using | ||
203 | the void function call init_autofs_dev_ioctl(struct autofs_dev_ioctl *). | ||
204 | |||
205 | All of the ioctls perform a copy of this structure from user space to | ||
206 | kernel space and return -EINVAL if the size parameter is smaller than | ||
207 | the structure size itself, -ENOMEM if the kernel memory allocation fails | ||
208 | or -EFAULT if the copy itself fails. Other checks include a version check | ||
209 | of the compiled in user space version against the module version and a | ||
210 | mismatch results in a -EINVAL return. If the size field is greater than | ||
211 | the structure size then a path is assumed to be present and is checked to | ||
212 | ensure it begins with a "/" and is NULL terminated, otherwise -EINVAL is | ||
213 | returned. Following these checks, for all ioctl commands except | ||
214 | AUTOFS_DEV_IOCTL_VERSION_CMD, AUTOFS_DEV_IOCTL_OPENMOUNT_CMD and | ||
215 | AUTOFS_DEV_IOCTL_CLOSEMOUNT_CMD the ioctlfd is validated and if it is | ||
216 | not a valid descriptor or doesn't correspond to an autofs mount point | ||
217 | an error of -EBADF, -ENOTTY or -EINVAL (not an autofs descriptor) is | ||
218 | returned. | ||
219 | |||
220 | |||
221 | The ioctls | ||
222 | ========== | ||
223 | |||
224 | An example of an implementation which uses this interface can be seen | ||
225 | in autofs version 5.0.4 and later in file lib/dev-ioctl-lib.c of the | ||
226 | distribution tar available for download from kernel.org in directory | ||
227 | /pub/linux/daemons/autofs/v5. | ||
228 | |||
229 | The device node ioctl operations implemented by this interface are: | ||
230 | |||
231 | |||
232 | AUTOFS_DEV_IOCTL_VERSION | ||
233 | ------------------------ | ||
234 | |||
235 | Get the major and minor version of the autofs4 device ioctl kernel module | ||
236 | implementation. It requires an initialized struct autofs_dev_ioctl as an | ||
237 | input parameter and sets the version information in the passed in structure. | ||
238 | It returns 0 on success or the error -EINVAL if a version mismatch is | ||
239 | detected. | ||
240 | |||
241 | |||
242 | AUTOFS_DEV_IOCTL_PROTOVER_CMD and AUTOFS_DEV_IOCTL_PROTOSUBVER_CMD | ||
243 | ------------------------------------------------------------------ | ||
244 | |||
245 | Get the major and minor version of the autofs4 protocol version understood | ||
246 | by loaded module. This call requires an initialized struct autofs_dev_ioctl | ||
247 | with the ioctlfd field set to a valid autofs mount point descriptor | ||
248 | and sets the requested version number in structure field arg1. These | ||
249 | commands return 0 on success or one of the negative error codes if | ||
250 | validation fails. | ||
251 | |||
252 | |||
253 | AUTOFS_DEV_IOCTL_OPENMOUNT and AUTOFS_DEV_IOCTL_CLOSEMOUNT | ||
254 | ---------------------------------------------------------- | ||
255 | |||
256 | Obtain and release a file descriptor for an autofs managed mount point | ||
257 | path. The open call requires an initialized struct autofs_dev_ioctl with | ||
258 | the the path field set and the size field adjusted appropriately as well | ||
259 | as the arg1 field set to the device number of the autofs mount. The | ||
260 | device number can be obtained from the mount options shown in | ||
261 | /proc/mounts. The close call requires an initialized struct | ||
262 | autofs_dev_ioct with the ioctlfd field set to the descriptor obtained | ||
263 | from the open call. The release of the file descriptor can also be done | ||
264 | with close(2) so any open descriptors will also be closed at process exit. | ||
265 | The close call is included in the implemented operations largely for | ||
266 | completeness and to provide for a consistent user space implementation. | ||
267 | |||
268 | |||
269 | AUTOFS_DEV_IOCTL_READY_CMD and AUTOFS_DEV_IOCTL_FAIL_CMD | ||
270 | -------------------------------------------------------- | ||
271 | |||
272 | Return mount and expire result status from user space to the kernel. | ||
273 | Both of these calls require an initialized struct autofs_dev_ioctl | ||
274 | with the ioctlfd field set to the descriptor obtained from the open | ||
275 | call and the arg1 field set to the wait queue token number, received | ||
276 | by user space in the foregoing mount or expire request. The arg2 field | ||
277 | is set to the status to be returned. For the ready call this is always | ||
278 | 0 and for the fail call it is set to the errno of the operation. | ||
279 | |||
280 | |||
281 | AUTOFS_DEV_IOCTL_SETPIPEFD_CMD | ||
282 | ------------------------------ | ||
283 | |||
284 | Set the pipe file descriptor used for kernel communication to the daemon. | ||
285 | Normally this is set at mount time using an option but when reconnecting | ||
286 | to a existing mount we need to use this to tell the autofs mount about | ||
287 | the new kernel pipe descriptor. In order to protect mounts against | ||
288 | incorrectly setting the pipe descriptor we also require that the autofs | ||
289 | mount be catatonic (see next call). | ||
290 | |||
291 | The call requires an initialized struct autofs_dev_ioctl with the | ||
292 | ioctlfd field set to the descriptor obtained from the open call and | ||
293 | the arg1 field set to descriptor of the pipe. On success the call | ||
294 | also 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 | |||
298 | AUTOFS_DEV_IOCTL_CATATONIC_CMD | ||
299 | ------------------------------ | ||
300 | |||
301 | Make the autofs mount point catatonic. The autofs mount will no longer | ||
302 | issue mount requests, the kernel communication pipe descriptor is released | ||
303 | and any remaining waits in the queue released. | ||
304 | |||
305 | The call requires an initialized struct autofs_dev_ioctl with the | ||
306 | ioctlfd field set to the descriptor obtained from the open call. | ||
307 | |||
308 | |||
309 | AUTOFS_DEV_IOCTL_TIMEOUT_CMD | ||
310 | ---------------------------- | ||
311 | |||
312 | Set the expire timeout for mounts withing an autofs mount point. | ||
313 | |||
314 | The call requires an initialized struct autofs_dev_ioctl with the | ||
315 | ioctlfd field set to the descriptor obtained from the open call. | ||
316 | |||
317 | |||
318 | AUTOFS_DEV_IOCTL_REQUESTER_CMD | ||
319 | ------------------------------ | ||
320 | |||
321 | Return the uid and gid of the last process to successfully trigger a the | ||
322 | mount on the given path dentry. | ||
323 | |||
324 | The call requires an initialized struct autofs_dev_ioctl with the path | ||
325 | field set to the mount point in question and the size field adjusted | ||
326 | appropriately as well as the arg1 field set to the device number of the | ||
327 | containing autofs mount. Upon return the struct field arg1 contains the | ||
328 | uid and arg2 the gid. | ||
329 | |||
330 | When reconstructing an autofs mount tree with active mounts we need to | ||
331 | re-connect to mounts that may have used the original process uid and | ||
332 | gid (or string variations of them) for mount lookups within the map entry. | ||
333 | This call provides the ability to obtain this uid and gid so they may be | ||
334 | used by user space for the mount map lookups. | ||
335 | |||
336 | |||
337 | AUTOFS_DEV_IOCTL_EXPIRE_CMD | ||
338 | --------------------------- | ||
339 | |||
340 | Issue an expire request to the kernel for an autofs mount. Typically | ||
341 | this ioctl is called until no further expire candidates are found. | ||
342 | |||
343 | The call requires an initialized struct autofs_dev_ioctl with the | ||
344 | ioctlfd field set to the descriptor obtained from the open call. In | ||
345 | addition an immediate expire, independent of the mount timeout, can be | ||
346 | requested by setting the arg1 field to 1. If no expire candidates can | ||
347 | be found the ioctl returns -1 with errno set to EAGAIN. | ||
348 | |||
349 | This call causes the kernel module to check the mount corresponding | ||
350 | to the given ioctlfd for mounts that can be expired, issues an expire | ||
351 | request back to the daemon and waits for completion. | ||
352 | |||
353 | AUTOFS_DEV_IOCTL_ASKUMOUNT_CMD | ||
354 | ------------------------------ | ||
355 | |||
356 | Checks if an autofs mount point is in use. | ||
357 | |||
358 | The call requires an initialized struct autofs_dev_ioctl with the | ||
359 | ioctlfd field set to the descriptor obtained from the open call and | ||
360 | it returns the result in the arg1 field, 1 for busy and 0 otherwise. | ||
361 | |||
362 | |||
363 | AUTOFS_DEV_IOCTL_ISMOUNTPOINT_CMD | ||
364 | --------------------------------- | ||
365 | |||
366 | Check if the given path is a mountpoint. | ||
367 | |||
368 | The call requires an initialized struct autofs_dev_ioctl. There are two | ||
369 | possible variations. Both use the path field set to the path of the mount | ||
370 | point to check and the size field adjusted appropriately. One uses the | ||
371 | ioctlfd field to identify a specific mount point to check while the other | ||
372 | variation uses the path and optionaly arg1 set to an autofs mount type. | ||
373 | The call returns 1 if this is a mount point and sets arg1 to the device | ||
374 | number of the mount and field arg2 to the relevant super block magic | ||
375 | number (described below) or 0 if it isn't a mountpoint. In both cases | ||
376 | the the device number (as returned by new_encode_dev()) is returned | ||
377 | in field arg1. | ||
378 | |||
379 | If supplied with a file descriptor we're looking for a specific mount, | ||
380 | not necessarily at the top of the mounted stack. In this case the path | ||
381 | the descriptor corresponds to is considered a mountpoint if it is itself | ||
382 | a mountpoint or contains a mount, such as a multi-mount without a root | ||
383 | mount. In this case we return 1 if the descriptor corresponds to a mount | ||
384 | point and and also returns the super magic of the covering mount if there | ||
385 | is one or 0 if it isn't a mountpoint. | ||
386 | |||
387 | If a path is supplied (and the ioctlfd field is set to -1) then the path | ||
388 | is looked up and is checked to see if it is the root of a mount. If a | ||
389 | type is also given we are looking for a particular autofs mount and if | ||
390 | a match isn't found a fail is returned. If the the located path is the | ||
391 | root of a mount 1 is returned along with the super magic of the mount | ||
392 | or 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/> | |||
193 | programs: http://e2fsprogs.sourceforge.net/ | 193 | programs: http://e2fsprogs.sourceforge.net/ |
194 | http://ext2resize.sourceforge.net | 194 | http://ext2resize.sourceforge.net |
195 | 195 | ||
196 | useful links: http://www.zip.com.au/~akpm/linux/ext3/ext3-usage.html | 196 | useful 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 @@ | |||
2 | Ext4 Filesystem | 2 | Ext4 Filesystem |
3 | =============== | 3 | =============== |
4 | 4 | ||
5 | This is a development version of the ext4 filesystem, an advanced level | 5 | Ext4 is an an advanced level of the ext3 filesystem which incorporates |
6 | of the ext3 filesystem which incorporates scalability and reliability | 6 | scalability and reliability enhancements for supporting large filesystems |
7 | enhancements for supporting large filesystems (64 bit) in keeping with | 7 | (64 bit) in keeping with increasing disk capacities and state-of-the-art |
8 | increasing disk capacities and state-of-the-art feature requirements. | 8 | feature requirements. |
9 | 9 | ||
10 | Mailing list: linux-ext4@vger.kernel.org | 10 | Mailing list: linux-ext4@vger.kernel.org |
11 | Web site: http://ext4.wiki.kernel.org | ||
11 | 12 | ||
12 | 13 | ||
13 | 1. Quick usage instructions: | 14 | 1. Quick usage instructions: |
14 | =========================== | 15 | =========================== |
15 | 16 | ||
17 | Note: 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. | |||
104 | The big performance win will come with mballoc, delalloc and flex_bg | 107 | The big performance win will come with mballoc, delalloc and flex_bg |
105 | grouping of bitmaps and inode tables. Some test results available here: | 108 | grouping 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 | ||
110 | 3. Options | 113 | 3. 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 | ||
183 | inode_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 | |||
180 | orlov (*) This enables the new Orlov block allocator. It is | 188 | orlov (*) This enables the new Orlov block allocator. It is |
181 | enabled by default. | 189 | enabled by default. |
182 | 190 | ||
@@ -209,15 +217,17 @@ noreservation | |||
209 | bsddf (*) Make 'df' act like BSD. | 217 | bsddf (*) Make 'df' act like BSD. |
210 | minixdf Make 'df' act like Minix. | 218 | minixdf Make 'df' act like Minix. |
211 | 219 | ||
212 | check=none Don't do extra checking of bitmaps on mount. | ||
213 | nocheck | ||
214 | |||
215 | debug Extra debugging information is sent to syslog. | 220 | debug Extra debugging information is sent to syslog. |
216 | 221 | ||
217 | errors=remount-ro(*) Remount the filesystem read-only on an error. | 222 | errors=remount-ro(*) Remount the filesystem read-only on an error. |
218 | errors=continue Keep going on a filesystem error. | 223 | errors=continue Keep going on a filesystem error. |
219 | errors=panic Panic and halt the machine if an error occurs. | 224 | errors=panic Panic and halt the machine if an error occurs. |
220 | 225 | ||
226 | data_err=ignore(*) Just print an error message if an error occurs | ||
227 | in a file data buffer in ordered mode. | ||
228 | data_err=abort Abort the journal if an error occurs in a file | ||
229 | data buffer in ordered mode. | ||
230 | |||
221 | grpid Give objects the same group ID as their creator. | 231 | grpid Give objects the same group ID as their creator. |
222 | bsdgroups | 232 | bsdgroups |
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 | ||
246 | mballoc (*) Use the multiple block allocator for block allocation | ||
247 | nomballoc disabled multiple block allocator for block allocation. | ||
248 | stripe=n Number of filesystem blocks that mballoc will try | 256 | stripe=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 | |||
252 | delalloc (*) Deferring block allocation until write-out time. | 260 | delalloc (*) Deferring block allocation until write-out time. |
253 | nodelalloc Disable delayed allocation. Blocks are allocation | 261 | nodelalloc 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 | |||
255 | Data Mode | 264 | Data Mode |
256 | ========= | 265 | ========= |
257 | There are 3 different data modes: | 266 | There 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 | ============ | ||
2 | Fiemap Ioctl | ||
3 | ============ | ||
4 | |||
5 | The fiemap ioctl is an efficient method for userspace to get file | ||
6 | extent mappings. Instead of block-by-block mapping (such as bmap), fiemap | ||
7 | returns a list of extents. | ||
8 | |||
9 | |||
10 | Request Basics | ||
11 | -------------- | ||
12 | |||
13 | A fiemap request is encoded within struct fiemap: | ||
14 | |||
15 | struct 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 | |||
29 | fm_start, and fm_length specify the logical range within the file | ||
30 | which the process would like mappings for. Extents returned mirror | ||
31 | those on disk - that is, the logical offset of the 1st returned extent | ||
32 | may start before fm_start, and the range covered by the last returned | ||
33 | extent may end after fm_length. All offsets and lengths are in bytes. | ||
34 | |||
35 | Certain flags to modify the way in which mappings are looked up can be | ||
36 | set in fm_flags. If the kernel doesn't understand some particular | ||
37 | flags, it will return EBADR and the contents of fm_flags will contain | ||
38 | the set of flags which caused the error. If the kernel is compatible | ||
39 | with all flags passed, the contents of fm_flags will be unmodified. | ||
40 | It is up to userspace to determine whether rejection of a particular | ||
41 | flag is fatal to it's operation. This scheme is intended to allow the | ||
42 | fiemap interface to grow in the future but without losing | ||
43 | compatibility with old software. | ||
44 | |||
45 | fm_extent_count specifies the number of elements in the fm_extents[] array | ||
46 | that can be used to return extents. If fm_extent_count is zero, then the | ||
47 | fm_extents[] array is ignored (no extents will be returned), and the | ||
48 | fm_mapped_extents count will hold the number of extents needed in | ||
49 | fm_extents[] to hold the file's current mapping. Note that there is | ||
50 | nothing to prevent the file from changing between calls to FIEMAP. | ||
51 | |||
52 | The following flags can be set in fm_flags: | ||
53 | |||
54 | * FIEMAP_FLAG_SYNC | ||
55 | If this flag is set, the kernel will sync the file before mapping extents. | ||
56 | |||
57 | * FIEMAP_FLAG_XATTR | ||
58 | If this flag is set, the extents returned will describe the inodes | ||
59 | extended attribute lookup tree, instead of it's data tree. | ||
60 | |||
61 | |||
62 | Extent Mapping | ||
63 | -------------- | ||
64 | |||
65 | Extent information is returned within the embedded fm_extents array | ||
66 | which userspace must allocate along with the fiemap structure. The | ||
67 | number of elements in the fiemap_extents[] array should be passed via | ||
68 | fm_extent_count. The number of extents mapped by kernel will be | ||
69 | returned via fm_mapped_extents. If the number of fiemap_extents | ||
70 | allocated is less than would be required to map the requested range, | ||
71 | the maximum number of extents that can be mapped in the fm_extent[] | ||
72 | array will be returned and fm_mapped_extents will be equal to | ||
73 | fm_extent_count. In that case, the last extent in the array will not | ||
74 | complete the requested range and will not have the FIEMAP_EXTENT_LAST | ||
75 | flag set (see the next section on extent flags). | ||
76 | |||
77 | Each extent is described by a single fiemap_extent structure as | ||
78 | returned in fm_extents. | ||
79 | |||
80 | struct 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 | |||
91 | All offsets and lengths are in bytes and mirror those on disk. It is valid | ||
92 | for an extents logical offset to start before the request or it's logical | ||
93 | length to extend past the request. Unless FIEMAP_EXTENT_NOT_ALIGNED is | ||
94 | returned, fe_logical, fe_physical, and fe_length will be aligned to the | ||
95 | block size of the file system. With the exception of extents flagged as | ||
96 | FIEMAP_EXTENT_MERGED, adjacent extents will not be merged. | ||
97 | |||
98 | The fe_flags field contains flags which describe the extent returned. | ||
99 | A special flag, FIEMAP_EXTENT_LAST is always set on the last extent in | ||
100 | the file so that the process making fiemap calls can determine when no | ||
101 | more extents are available, without having to call the ioctl again. | ||
102 | |||
103 | Some flags are intentionally vague and will always be set in the | ||
104 | presence of other more specific flags. This way a program looking for | ||
105 | a general property does not have to know all existing and future flags | ||
106 | which imply that property. | ||
107 | |||
108 | For example, if FIEMAP_EXTENT_DATA_INLINE or FIEMAP_EXTENT_DATA_TAIL | ||
109 | are set, FIEMAP_EXTENT_NOT_ALIGNED will also be set. A program looking | ||
110 | for inline or tail-packed data can key on the specific flag. Software | ||
111 | which simply cares not to try operating on non-aligned extents | ||
112 | however, can just key on FIEMAP_EXTENT_NOT_ALIGNED, and not have to | ||
113 | worry about all present and future flags which might imply unaligned | ||
114 | data. Note that the opposite is not true - it would be valid for | ||
115 | FIEMAP_EXTENT_NOT_ALIGNED to appear alone. | ||
116 | |||
117 | * FIEMAP_EXTENT_LAST | ||
118 | This is the last extent in the file. A mapping attempt past this | ||
119 | extent will return nothing. | ||
120 | |||
121 | * FIEMAP_EXTENT_UNKNOWN | ||
122 | The location of this extent is currently unknown. This may indicate | ||
123 | the data is stored on an inaccessible volume or that no storage has | ||
124 | been allocated for the file yet. | ||
125 | |||
126 | * FIEMAP_EXTENT_DELALLOC | ||
127 | - This will also set FIEMAP_EXTENT_UNKNOWN. | ||
128 | Delayed allocation - while there is data for this extent, it's | ||
129 | physical location has not been allocated yet. | ||
130 | |||
131 | * FIEMAP_EXTENT_ENCODED | ||
132 | This extent does not consist of plain filesystem blocks but is | ||
133 | encoded (e.g. encrypted or compressed). Reading the data in this | ||
134 | extent via I/O to the block device will have undefined results. | ||
135 | |||
136 | Note that it is *always* undefined to try to update the data | ||
137 | in-place by writing to the indicated location without the | ||
138 | assistance of the filesystem, or to access the data using the | ||
139 | information returned by the FIEMAP interface while the filesystem | ||
140 | is mounted. In other words, user applications may only read the | ||
141 | extent data via I/O to the block device while the filesystem is | ||
142 | unmounted, and then only if the FIEMAP_EXTENT_ENCODED flag is | ||
143 | clear; user applications must not try reading or writing to the | ||
144 | filesystem via the block device under any other circumstances. | ||
145 | |||
146 | * FIEMAP_EXTENT_DATA_ENCRYPTED | ||
147 | - This will also set FIEMAP_EXTENT_ENCODED | ||
148 | The data in this extent has been encrypted by the file system. | ||
149 | |||
150 | * FIEMAP_EXTENT_NOT_ALIGNED | ||
151 | Extent 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 | ||
155 | Data is located within a meta data block. | ||
156 | |||
157 | * FIEMAP_EXTENT_DATA_TAIL | ||
158 | This will also set FIEMAP_EXTENT_NOT_ALIGNED | ||
159 | Data is packed into a block with data from other files. | ||
160 | |||
161 | * FIEMAP_EXTENT_UNWRITTEN | ||
162 | Unwritten extent - the extent is allocated but it's data has not been | ||
163 | initialized. This indicates the extent's data will be all zero if read | ||
164 | through the filesystem but the contents are undefined if read directly from | ||
165 | the device. | ||
166 | |||
167 | * FIEMAP_EXTENT_MERGED | ||
168 | This will be set when a file does not support extents, i.e., it uses a block | ||
169 | based addressing scheme. Since returning an extent for each block back to | ||
170 | userspace would be highly inefficient, the kernel will try to merge most | ||
171 | adjacent blocks into 'extents'. | ||
172 | |||
173 | |||
174 | VFS -> File System Implementation | ||
175 | --------------------------------- | ||
176 | |||
177 | File systems wishing to support fiemap must implement a ->fiemap callback on | ||
178 | their inode_operations structure. The fs ->fiemap call is responsible for | ||
179 | defining it's set of supported fiemap flags, and calling a helper function on | ||
180 | each discovered extent: | ||
181 | |||
182 | struct 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 | ||
189 | fiemap request: | ||
190 | |||
191 | struct 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 | |||
198 | It is intended that the file system should not need to access any of this | ||
199 | structure directly. | ||
200 | |||
201 | |||
202 | Flag checking should be done at the beginning of the ->fiemap callback via the | ||
203 | fiemap_check_flags() helper: | ||
204 | |||
205 | int fiemap_check_flags(struct fiemap_extent_info *fieinfo, u32 fs_flags); | ||
206 | |||
207 | The struct fieinfo should be passed in as recieved from ioctl_fiemap(). The | ||
208 | set of fiemap flags which the fs understands should be passed via fs_flags. If | ||
209 | fiemap_check_flags finds invalid user flags, it will place the bad values in | ||
210 | fieinfo->fi_flags and return -EBADR. If the file system gets -EBADR, from | ||
211 | fiemap_check_flags(), it should immediately exit, returning that error back to | ||
212 | ioctl_fiemap(). | ||
213 | |||
214 | |||
215 | For each extent in the request range, the file system should call | ||
216 | the helper function, fiemap_fill_next_extent(): | ||
217 | |||
218 | int fiemap_fill_next_extent(struct fiemap_extent_info *info, u64 logical, | ||
219 | u64 phys, u64 len, u32 flags, u32 dev); | ||
220 | |||
221 | fiemap_fill_next_extent() will use the passed values to populate the | ||
222 | next free extent in the fm_extents array. 'General' extent flags will | ||
223 | automatically be set from specific flags on behalf of the calling file | ||
224 | system so that the userspace API is not broken. | ||
225 | |||
226 | fiemap_fill_next_extent() returns 0 on success, and 1 when the | ||
227 | user-supplied fm_extents array is full. If an error is encountered | ||
228 | while 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: | |||
169 | 3.1) Booting from a floppy using syslinux | 169 | 3.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. |
78 | localflocks This disables cluster aware flock. | 78 | localflocks This disables cluster aware flock. |
79 | inode64 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. | ||
83 | user_xattr (*) Enables Extended User Attributes. | ||
84 | nouser_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. | |||
923 | The "procs_blocked" line gives the number of processes currently blocked, | 923 | The "procs_blocked" line gives the number of processes currently blocked, |
924 | waiting for I/O to complete. | 924 | waiting for I/O to complete. |
925 | 925 | ||
926 | |||
926 | 1.9 Ext4 file system parameters | 927 | 1.9 Ext4 file system parameters |
927 | ------------------------------ | 928 | ------------------------------ |
928 | Ext4 file system have one directory per partition under /proc/fs/ext4/ | ||
929 | # ls /proc/fs/ext4/hdc/ | ||
930 | group_prealloc max_to_scan mb_groups mb_history min_to_scan order2_req | ||
931 | stats stream_req | ||
932 | |||
933 | mb_groups: | ||
934 | This file gives the details of multiblock allocator buddy cache of free blocks | ||
935 | |||
936 | mb_history: | ||
937 | Multiblock allocation history. | ||
938 | |||
939 | stats: | ||
940 | This file indicate whether the multiblock allocator should start collecting | ||
941 | statistics. The statistics are shown during unmount | ||
942 | 929 | ||
943 | group_prealloc: | 930 | Information about mounted ext4 file systems can be found in |
944 | The multiblock allocator normalize the block allocation request to | 931 | /proc/fs/ext4. Each mounted filesystem will have a directory in |
945 | group_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 |
946 | The 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 |
934 | in Table 1-10, below. | ||
947 | 935 | ||
948 | max_to_scan: | 936 | Table 1-10: Files in /proc/fs/ext4/<devname> |
949 | How long multiblock allocator can look for a best extent (in found extents) | 937 | .............................................................................. |
950 | 938 | File Content | |
951 | min_to_scan: | 939 | mb_groups details of multiblock allocator buddy cache of free blocks |
952 | How 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 | |
954 | order2_req: | 942 | collecting statistics, which are shown during the unmount |
955 | Multiblock allocator use 2^N search using buddies only for requests greater | 943 | group_prealloc the multiblock allocator will round up allocation |
956 | than or equal to order2_req. The request size is specfied in file system | 944 | requests to a multiple of this tuning parameter if the |
957 | blocks. A value of 2 indicate only if the requests are greater than or equal | 945 | stripe size is not set in the ext4 superblock |
958 | to 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. | ||
959 | inode_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 | ||
960 | stream_req: | ||
961 | Files smaller than stream_req are served by the stream allocator, whose | ||
962 | purpose is to pack requests as close each to other as possible to | ||
963 | produce smooth I/O traffic. Avalue of 16 indicate that file smaller than 16 | ||
964 | filesystem block size will use group based preallocation. | ||
965 | 964 | ||
966 | ------------------------------------------------------------------------------ | 965 | ------------------------------------------------------------------------------ |
967 | Summary | 966 | Summary |
@@ -1322,6 +1321,18 @@ debugging information is displayed on console. | |||
1322 | NMI switch that most IA32 servers have fires unknown NMI up, for example. | 1321 | NMI switch that most IA32 servers have fires unknown NMI up, for example. |
1323 | If a system hangs up, try pressing the NMI switch. | 1322 | If a system hangs up, try pressing the NMI switch. |
1324 | 1323 | ||
1324 | panic_on_unrecovered_nmi | ||
1325 | ------------------------ | ||
1326 | |||
1327 | The default Linux behaviour on an NMI of either memory or unknown is to continue | ||
1328 | operation. For many environments such as scientific computing it is preferable | ||
1329 | that the box is taken out and the error dealt with than an uncorrected | ||
1330 | parity/ECC error get propogated. | ||
1331 | |||
1332 | A small number of systems do generate NMI's for bizarre random reasons such as | ||
1333 | power management so the default is off. That sysctl works like the existing | ||
1334 | panic controls already in that directory. | ||
1335 | |||
1325 | nmi_watchdog | 1336 | nmi_watchdog |
1326 | ------------ | 1337 | ------------ |
1327 | 1338 | ||
@@ -1332,13 +1343,6 @@ determine whether or not they are still functioning properly. | |||
1332 | Because the NMI watchdog shares registers with oprofile, by disabling the NMI | 1343 | Because the NMI watchdog shares registers with oprofile, by disabling the NMI |
1333 | watchdog, oprofile may have more registers to utilize. | 1344 | watchdog, oprofile may have more registers to utilize. |
1334 | 1345 | ||
1335 | maps_protect | ||
1336 | ------------ | ||
1337 | |||
1338 | Enables/Disables the protection of the per-process proc entries "maps" and | ||
1339 | "smaps". When enabled, the contents of these files are visible only to | ||
1340 | readers that are allowed to ptrace() the given process. | ||
1341 | |||
1342 | msgmni | 1346 | msgmni |
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 | |||
240 | needed to manage a signal that's in active use. That is, requesting a | 240 | needed to manage a signal that's in active use. That is, requesting a |
241 | GPIO can serve as a kind of lock. | 241 | GPIO can serve as a kind of lock. |
242 | 242 | ||
243 | Some platforms may also use knowledge about what GPIOs are active for | ||
244 | power management, such as by powering down unused chip sectors and, more | ||
245 | easily, gating off unused clocks. | ||
246 | |||
243 | These two calls are optional because not not all current Linux platforms | 247 | These two calls are optional because not not all current Linux platforms |
244 | offer such functionality in their GPIO support; a valid implementation | 248 | offer such functionality in their GPIO support; a valid implementation |
245 | could return success for all gpio_request() calls. Unlike the other calls, | 249 | could 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 | ||
270 | Those return either the corresponding number in the other namespace, or | 274 | Those return either the corresponding number in the other namespace, or |
@@ -284,7 +288,8 @@ system wakeup capabilities. | |||
284 | 288 | ||
285 | Non-error values returned from irq_to_gpio() would most commonly be used | 289 | Non-error values returned from irq_to_gpio() would most commonly be used |
286 | with gpio_get_value(), for example to initialize or update driver state | 290 | with gpio_get_value(), for example to initialize or update driver state |
287 | when the IRQ is edge-triggered. | 291 | when the IRQ is edge-triggered. Note that some platforms don't support |
292 | this reverse mapping, so you should avoid using it. | ||
288 | 293 | ||
289 | 294 | ||
290 | Emulating Open Drain Signals | 295 | Emulating 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 @@ | |||
1 | Kernel driver adt7470 | ||
2 | ===================== | ||
3 | |||
4 | Supported 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 | |||
10 | Author: Darrick J. Wong | ||
11 | |||
12 | Description | ||
13 | ----------- | ||
14 | |||
15 | This driver implements support for the Analog Devices ADT7470 chip. There may | ||
16 | be other chips that implement this interface. | ||
17 | |||
18 | The ADT7470 uses the 2-wire interface compatible with the SMBus 2.0 | ||
19 | specification. Using an analog to digital converter it measures up to ten (10) | ||
20 | external temperatures. It has four (4) 16-bit counters for measuring fan speed. | ||
21 | There are four (4) PWM outputs that can be used to control fan speed. | ||
22 | |||
23 | A sophisticated control system for the PWM outputs is designed into the ADT7470 | ||
24 | that allows fan speed to be adjusted automatically based on any of the ten | ||
25 | temperature sensors. Each PWM output is individually adjustable and | ||
26 | programmable. Once configured, the ADT7470 will adjust the PWM outputs in | ||
27 | response to the measured temperatures with further host intervention. This | ||
28 | feature can also be disabled for manual control of the PWM's. | ||
29 | |||
30 | Each of the measured inputs (temperature, fan speed) has corresponding high/low | ||
31 | limit values. The ADT7470 will signal an ALARM if any measured value exceeds | ||
32 | either limit. | ||
33 | |||
34 | The ADT7470 DOES NOT sample all inputs continuously. A single pin on the | ||
35 | ADT7470 is connected to a multitude of thermal diodes, but the chip must be | ||
36 | instructed explicitly to read the multitude of diodes. If you want to use | ||
37 | automatic fan control mode, you must manually read any of the temperature | ||
38 | sensors or the fan control algorithm will not run. The chip WILL NOT DO THIS | ||
39 | AUTOMATICALLY; this must be done from userspace. This may be a bug in the chip | ||
40 | design, given that many other AD chips take care of this. The driver will not | ||
41 | read the registers more often than once every 5 seconds. Further, | ||
42 | configuration data is only read once per minute. | ||
43 | |||
44 | Special Features | ||
45 | ---------------- | ||
46 | |||
47 | The ADT7470 has a 8-bit ADC and is capable of measuring temperatures with 1 | ||
48 | degC resolution. | ||
49 | |||
50 | The Analog Devices datasheet is very detailed and describes a procedure for | ||
51 | determining an optimal configuration for the automatic PWM control. | ||
52 | |||
53 | Configuration Notes | ||
54 | ------------------- | ||
55 | |||
56 | Besides 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 | |||
63 | point1: Set the pwm speed at a lower temperature bound. | ||
64 | point2: Set the pwm speed at a higher temperature bound. | ||
65 | |||
66 | The ADT7470 will scale the pwm between the lower and higher pwm speed when | ||
67 | the temperature is between the two temperature boundaries. PWM values range | ||
68 | from 0 (off) to 255 (full speed). Fan speed will be set to maximum when the | ||
69 | temperature sensor associated with the PWM control exceeds | ||
70 | pwm#_auto_point2_temp. | ||
71 | |||
72 | Notes | ||
73 | ----- | ||
74 | |||
75 | As stated above, the temperature inputs must be read periodically from | ||
76 | userspace 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. | |||
136 | The IT87xx only updates its values each 1.5 seconds; reading it more often | 136 | The IT87xx only updates its values each 1.5 seconds; reading it more often |
137 | will do no harm, but will return 'old' values. | 137 | will do no harm, but will return 'old' values. |
138 | 138 | ||
139 | To change sensor N to a thermistor, 'echo 2 > tempN_type' where N is 1, 2, | 139 | To change sensor N to a thermistor, 'echo 4 > tempN_type' where N is 1, 2, |
140 | or 3. To change sensor N to a thermal diode, 'echo 3 > tempN_type'. | 140 | or 3. To change sensor N to a thermal diode, 'echo 3 > tempN_type'. |
141 | Give 0 for unused sensor. Any other value is invalid. To configure this at | 141 | Give 0 for unused sensor. Any other value is invalid. To configure this at |
142 | startup, consult lm_sensors's /etc/sensors.conf. (2 = thermistor; | 142 | startup, consult lm_sensors's /etc/sensors.conf. (4 = thermistor; |
143 | 3 = thermal diode) | 143 | 3 = 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 | |||
170 | The pwm#_auto_pwm_freq can be set to one of the following 8 values. Setting the | ||
171 | frequency to a value not on this list, will result in the next higher frequency | ||
172 | being selected. The actual device frequency may vary slightly from this | ||
173 | specification as designed by the manufacturer. Consult the datasheet for more | ||
174 | details. (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, | |||
65 | depending on the hardware configuration. | 65 | depending on the hardware configuration. |
66 | 66 | ||
67 | Some functions share pins, so not all functions are available at the same | 67 | Some functions share pins, so not all functions are available at the same |
68 | time. Which are depends on the hardware setup. This driver assumes that | 68 | time. Which are depends on the hardware setup. This driver normally |
69 | the BIOS configured the chip correctly. In that respect, it differs from | 69 | assumes that firmware configured the chip correctly. Where this is not |
70 | the original driver (from lm_sensors for Linux 2.4), which would force the | 70 | the case, platform code must set the I2C client's platform_data to point |
71 | LM87 to an arbitrary, compile-time chosen mode, regardless of the actual | 71 | to a u8 value to be written to the channel register. |
72 | chipset wiring. | ||
73 | 72 | ||
74 | For reference, here is the list of exclusive functions: | 73 | For 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 | ||
71 | The LM90 is a digital temperature sensor. It senses its own temperature as | 85 | The LM90 is a digital temperature sensor. It senses its own temperature as |
72 | well as the temperature of up to one external diode. It is compatible | 86 | well as the temperature of up to one external diode. It is compatible |
73 | with many other devices such as the LM86, the LM89, the LM99, the ADM1032, | 87 | with many other devices, many of which are supported by this driver. |
74 | the MAX6657, MAX6658, MAX6659, MAX6680 and the MAX6681 all of which are | ||
75 | supported by this driver. | ||
76 | 88 | ||
77 | Note that there is no easy way to differentiate between the MAX6657, | 89 | Note that there is no easy way to differentiate between the MAX6657, |
78 | MAX6658 and MAX6659 variants. The extra address and features of the | 90 | MAX6658 and MAX6659 variants. The extra address and features of the |
79 | MAX6659 are not supported by this driver. The MAX6680 and MAX6681 only | 91 | MAX6659 are not supported by this driver. The MAX6680 and MAX6681 only |
80 | differ in their pinout, therefore they obviously can't (and don't need to) | 92 | differ in their pinout, therefore they obviously can't (and don't need to) |
81 | be distinguished. Additionally, the ADT7461 is supported if found in | 93 | be distinguished. |
82 | ADM1032 compatibility mode. | ||
83 | 94 | ||
84 | The specificity of this family of chipsets over the ADM1021/LM84 | 95 | The specificity of this family of chipsets over the ADM1021/LM84 |
85 | family is that it features critical limits with hysteresis, and an | 96 | family is that it features critical limits with hysteresis, and an |
86 | increased resolution of the remote temperature measurement. | 97 | increased resolution of the remote temperature measurement. |
87 | 98 | ||
88 | The different chipsets of the family are not strictly identical, although | 99 | The different chipsets of the family are not strictly identical, although |
89 | very similar. This driver doesn't handle any specific feature for now, | 100 | very similar. For reference, here comes a non-exhaustive list of specific |
90 | with the exception of SMBus PEC. For reference, here comes a non-exhaustive | 101 | features: |
91 | list of specific features: | ||
92 | 102 | ||
93 | LM90: | 103 | LM90: |
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 | ||
116 | MAX6657 and MAX6658: | 126 | MAX6657 and MAX6658: |
127 | * Better local resolution | ||
117 | * Remote sensor type selection | 128 | * Remote sensor type selection |
118 | 129 | ||
119 | MAX6659: | 130 | MAX6659: |
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 | ||
128 | All temperature values are given in degrees Celsius. Resolution | 140 | All temperature values are given in degrees Celsius. Resolution |
129 | is 1.0 degree for the local temperature, 0.125 degree for the remote | 141 | is 1.0 degree for the local temperature, 0.125 degree for the remote |
130 | temperature. | 142 | temperature, except for the MAX6657, MAX6658 and MAX6659 which have a |
143 | resolution of 0.125 degree for both temperatures. | ||
131 | 144 | ||
132 | Each sensor has its own high and low limits, plus a critical limit. | 145 | Each sensor has its own high and low limits, plus a critical limit. |
133 | Additionally, there is a relative hysteresis value common to both critical | 146 | Additionally, 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 | ||
15 | Authors: Jean Delvare <khali@linux-fr.org> | 10 | Authors: 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 | ||
10 | Author: Jean Delvare <khali@linux-fr.org> | 10 | Author: 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 | ||
356 | Additional info about PWM on the AS99127F (may apply to other Asus | 356 | * Additional info about PWM on the AS99127F (may apply to other Asus |
357 | chips as well) by Jean Delvare as of 2004-04-09: | 357 | chips as well) by Jean Delvare as of 2004-04-09: |
358 | 358 | ||
359 | AS99127F revision 2 seems to have two PWM registers at 0x59 and 0x5A, | 359 | AS99127F 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 | |||
396 | long as we don't know more, the w83781d driver doesn't handle PWM on | 396 | long as we don't know more, the w83781d driver doesn't handle PWM on |
397 | AS99127F chips at all. | 397 | AS99127F chips at all. |
398 | 398 | ||
399 | Additional 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 | ||
401 | I've been fiddling around with the (in)famous 0x59 register and | 401 | I've been fiddling around with the (in)famous 0x59 register and |
402 | found out the following values do work as a form of coarse pwm: | 402 | found out the following values do work as a form of coarse pwm: |
@@ -418,3 +418,36 @@ change. | |||
418 | My mobo is an ASUS A7V266-E. This behavior is similar to what I got | 418 | My mobo is an ASUS A7V266-E. This behavior is similar to what I got |
419 | with speedfan under Windows, where 0-15% would be off, 15-2x% (can't | 419 | with speedfan under Windows, where 0-15% would be off, 15-2x% (can't |
420 | remember the exact value) would be 70% and higher would be full on. | 420 | remember 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 | |||
425 | I conducted some experiment on Asus P3B-F motherboard with AS99127F | ||
426 | (Ver. 1). | ||
427 | |||
428 | I confirm that 0x59 register control the CPU_Fan Header on this | ||
429 | motherboard, and 0x5a register control PWR_Fan. | ||
430 | |||
431 | In order to reduce the dependency of specific fan, the measurement is | ||
432 | conducted with a digital scope without fan connected. I found out that | ||
433 | P3B-F actually output variable DC voltage on fan header center pin, | ||
434 | looks like PWM is filtered on this motherboard. | ||
435 | |||
436 | Here are some of measurements: | ||
437 | |||
438 | 0x80 20 mV | ||
439 | 0x81 20 mV | ||
440 | 0x82 232 mV | ||
441 | 0x83 1.2 V | ||
442 | 0x84 2.31 V | ||
443 | 0x85 3.44 V | ||
444 | 0x86 4.62 V | ||
445 | 0x87 5.81 V | ||
446 | 0x88 7.01 V | ||
447 | 9x89 8.22 V | ||
448 | 0x8a 9.42 V | ||
449 | 0x8b 10.6 V | ||
450 | 0x8c 11.9 V | ||
451 | 0x8d 12.4 V | ||
452 | 0x8e 12.4 V | ||
453 | 0x8f 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 | |||
58 | currently selected). If you know the address of the chip, use a 'force' | 58 | currently selected). If you know the address of the chip, use a 'force' |
59 | parameter; this will put it into a more well-behaved state first. | 59 | parameter; this will put it into a more well-behaved state first. |
60 | 60 | ||
61 | The driver implements three temperature sensors, five fan rotation speed | 61 | The driver implements three temperature sensors, ten voltage sensors, |
62 | sensors, and ten voltage sensors. | 62 | five fan rotation speed sensors and manual PWM control of each fan. |
63 | 63 | ||
64 | Temperatures are measured in degrees Celsius and measurement resolution is 1 | 64 | Temperatures are measured in degrees Celsius and measurement resolution is 1 |
65 | degC for temp1 and 0.5 degC for temp2 and temp3. An alarm is triggered when | 65 | degC for temp1 and 0.5 degC for temp2 and temp3. An alarm is triggered when |
66 | the temperature gets higher than the Overtemperature Shutdown value; it stays | 66 | the temperature gets higher than the Overtemperature Shutdown value; it stays |
67 | on until the temperature falls below the Hysteresis value. | 67 | on until the temperature falls below the Hysteresis value. |
68 | 68 | ||
69 | Voltage sensors (also known as IN sensors) report their values in millivolts. | ||
70 | An alarm is triggered if the voltage has crossed a programmable minimum | ||
71 | or maximum limit. | ||
72 | |||
69 | Fan rotation speeds are reported in RPM (rotations per minute). An alarm is | 73 | Fan rotation speeds are reported in RPM (rotations per minute). An alarm is |
70 | triggered if the rotation speed has dropped below a programmable limit. Fan | 74 | triggered if the rotation speed has dropped below a programmable limit. Fan |
71 | readings can be divided by a programmable divider (1, 2, 4, 8, 16, | 75 | readings can be divided by a programmable divider (1, 2, 4, 8, 16, |
72 | 32, 64 or 128 for all fans) to give the readings more range or accuracy. | 76 | 32, 64 or 128 for all fans) to give the readings more range or accuracy. |
73 | 77 | ||
74 | Voltage sensors (also known as IN sensors) report their values in millivolts. | 78 | Each fan controlled is controlled by PWM. The PWM duty cycle can be read and |
75 | An alarm is triggered if the voltage has crossed a programmable minimum | 79 | set for each fan separately. Valid values range from 0 (stop) to 255 (full). |
76 | or maximum limit. | 80 | PWM 1-3 support Thermal Cruise mode, in which the PWMs are automatically |
81 | regulated to keep respectively temp 1-3 at a certain target temperature. | ||
82 | See below for the description of the sysfs-interface. | ||
77 | 83 | ||
78 | The w83791d has a global bit used to enable beeping from the speaker when an | 84 | The w83791d has a global bit used to enable beeping from the speaker when an |
79 | alarm is triggered as well as a bitmask to enable or disable the beep for | 85 | alarm is triggered as well as a bitmask to enable or disable the beep for |
80 | specific alarms. You need both the global beep enable bit and the | 86 | specific alarms. You need both the global beep enable bit and the |
81 | corresponding beep bit to be on for a triggered alarm to sound a beep. | 87 | corresponding beep bit to be on for a triggered alarm to sound a beep. |
82 | 88 | ||
83 | The sysfs interface to the gloabal enable is via the sysfs beep_enable file. | 89 | The sysfs interface to the global enable is via the sysfs beep_enable file. |
84 | This file is used for both legacy and new code. | 90 | This file is used for both legacy and new code. |
85 | 91 | ||
86 | The sysfs interface to the beep bitmask has migrated from the original legacy | 92 | The sysfs interface to the beep bitmask has migrated from the original legacy |
@@ -105,6 +111,27 @@ going forward. | |||
105 | The driver reads the hardware chip values at most once every three seconds. | 111 | The driver reads the hardware chip values at most once every three seconds. |
106 | User mode code requesting values more often will receive cached values. | 112 | User mode code requesting values more often will receive cached values. |
107 | 113 | ||
114 | /sys files | ||
115 | ---------- | ||
116 | The sysfs-interface is documented in the 'sysfs-interface' file. Only | ||
117 | chip-specific options are documented here. | ||
118 | |||
119 | pwm[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 | |||
125 | temp[1-3]_target - defines the target temperature for Thermal Cruise mode. | ||
126 | Unit: millidegree Celsius | ||
127 | RW | ||
128 | |||
129 | temp[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 | |||
108 | Alarms bitmap vs. beep_mask bitmask | 135 | Alarms bitmap vs. beep_mask bitmask |
109 | ------------------------------------ | 136 | ------------------------------------ |
110 | For legacy code using the alarms and beep_mask files: | 137 | For legacy code using the alarms and beep_mask files: |
@@ -132,7 +159,3 @@ tart2 : alarms: 0x020000 beep_mask: 0x080000 <== mismatch | |||
132 | tart3 : alarms: 0x040000 beep_mask: 0x100000 <== mismatch | 159 | tart3 : alarms: 0x040000 beep_mask: 0x100000 <== mismatch |
133 | case_open : alarms: 0x001000 beep_mask: 0x001000 | 160 | case_open : alarms: 0x001000 beep_mask: 0x001000 |
134 | global_enable: alarms: -------- beep_mask: 0x800000 (modified via beep_enable) | 161 | global_enable: alarms: -------- beep_mask: 0x800000 (modified via beep_enable) |
135 | |||
136 | W83791D TODO: | ||
137 | --------------- | ||
138 | Provide 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 | |||
19 | Authors: | 22 | Authors: |
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 | ||
53 | If none of these show up, you should look in the BIOS for settings like | 57 | If none of these show up, you should look in the BIOS for settings like |
54 | enable ACPI / SMBus or even USB. | 58 | enable ACPI / SMBus or even USB. |
@@ -57,5 +61,5 @@ Except for the oldest chips (VT82C596A/B, VT82C686A and most probably | |||
57 | VT8231), this driver supports I2C block transactions. Such transactions | 61 | VT8231), this driver supports I2C block transactions. Such transactions |
58 | are mainly useful to read from and write to EEPROMs. | 62 | are mainly useful to read from and write to EEPROMs. |
59 | 63 | ||
60 | The CX700 additionally appears to support SMBus PEC, although this driver | 64 | The CX700/VX800/VX820 additionally appears to support SMBus PEC, although |
61 | doesn't implement it yet. | 65 | this 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 | ||
5 | Each registered i2c adapter gets a number, counting from 0. You can | 5 | Each registered i2c adapter gets a number, counting from 0. You can |
6 | examine /sys/class/i2c-dev/ to see what number corresponds to which adapter. | 6 | examine /sys/class/i2c-dev/ to see what number corresponds to which adapter. |
7 | Alternatively, you can run "i2cdetect -l" to obtain a formated list of all | ||
8 | i2c adapters present on your system at a given time. i2cdetect is part of | ||
9 | the i2c-tools package. | ||
10 | |||
7 | I2C device files are character device files with major device number 89 | 11 | I2C device files are character device files with major device number 89 |
8 | and a minor device number corresponding to the number assigned as | 12 | and a minor device number corresponding to the number assigned as |
9 | explained above. They should be called "i2c-%d" (i2c-0, i2c-1, ..., | 13 | explained 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 | |||
17 | first thing to do is "#include <linux/i2c-dev.h>". Please note that | 21 | first thing to do is "#include <linux/i2c-dev.h>". Please note that |
18 | there are two files named "i2c-dev.h" out there, one is distributed | 22 | there are two files named "i2c-dev.h" out there, one is distributed |
19 | with the Linux kernel and is meant to be included from kernel | 23 | with the Linux kernel and is meant to be included from kernel |
20 | driver code, the other one is distributed with lm_sensors and is | 24 | driver code, the other one is distributed with i2c-tools and is |
21 | meant to be included from user-space programs. You obviously want | 25 | meant to be included from user-space programs. You obviously want |
22 | the second one here. | 26 | the second one here. |
23 | 27 | ||
24 | Now, you have to decide which adapter you want to access. You should | 28 | Now, you have to decide which adapter you want to access. You should |
25 | inspect /sys/class/i2c-dev/ to decide this. Adapter numbers are assigned | 29 | inspect /sys/class/i2c-dev/ or run "i2cdetect -l" to decide this. |
26 | somewhat dynamically, so you can not even assume /dev/i2c-0 is the | 30 | Adapter numbers are assigned somewhat dynamically, so you can not |
27 | first adapter. | 31 | assume much about them. They can even change from one boot to the next. |
28 | 32 | ||
29 | Next thing, open the device file, as follows: | 33 | Next 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 | ||
40 | When you have opened the device, you must specify with what device | 46 | When you have opened the device, you must specify with what device |
41 | address you want to communicate: | 47 | address 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: | |||
48 | Well, you are all set up now. You can now use SMBus commands or plain | 56 | Well, you are all set up now. You can now use SMBus commands or plain |
49 | I2C to communicate with your device. SMBus commands are preferred if | 57 | I2C to communicate with your device. SMBus commands are preferred if |
50 | the device supports them. Both are illustrated below. | 58 | the 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 | ||
88 | Note that only a subset of the I2C and SMBus protocols can be achieved by | ||
89 | the means of read() and write() calls. In particular, so-called combined | ||
90 | transactions (mixing read and write messages in the same transaction) | ||
91 | aren't supported. For this reason, this interface is almost never used by | ||
92 | user-space programs. | ||
93 | |||
76 | IMPORTANT: because of the use of inline functions, you *have* to use | 94 | IMPORTANT: 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 | |||
80 | Full interface description | 98 | Full interface description |
81 | ========================== | 99 | ========================== |
82 | 100 | ||
83 | The following IOCTLs are defined and fully supported | 101 | The following IOCTLs are defined: |
84 | (see also i2c-dev.h): | ||
85 | 102 | ||
86 | ioctl(file,I2C_SLAVE,long addr) | 103 | ioctl(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 | ||
91 | ioctl(file,I2C_TENBIT,long select) | 108 | ioctl(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 | ||
96 | ioctl(file,I2C_PEC,long select) | 113 | ioctl(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 | ||
103 | ioctl(file,I2C_FUNCS,unsigned long *funcs) | 120 | ioctl(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 | ||
106 | ioctl(file,I2C_RDWR,struct i2c_rdwr_ioctl_data *msgset) | 123 | ioctl(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 | 139 | ioctl(file, I2C_SMBUS, struct i2c_smbus_ioctl_data *args) | |
124 | Other values are NOT supported at this moment, except for I2C_SMBUS, | 140 | Not meant to be called directly; instead, use the access functions |
125 | which you should never directly call; instead, use the access functions | 141 | below. |
126 | below. | ||
127 | 142 | ||
128 | You can do plain i2c transactions by using read(2) and write(2) calls. | 143 | You can do plain i2c transactions by using read(2) and write(2) calls. |
129 | You do not need to pass the address byte; instead, set it through | 144 | You 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 | |||
148 | returns the number of values read. The block buffers need not be longer | 163 | returns the number of values read. The block buffers need not be longer |
149 | than 32 bytes. | 164 | than 32 bytes. |
150 | 165 | ||
151 | The above functions are all macros, that resolve to calls to the | 166 | The above functions are all inline functions, that resolve to calls to |
152 | i2c_smbus_access function, that on its turn calls a specific ioctl | 167 | the i2c_smbus_access function, that on its turn calls a specific ioctl |
153 | with the data in a specific format. Read the source code if you | 168 | with the data in a specific format. Read the source code if you |
154 | want to know what happens behind the screens. | 169 | want to know what happens behind the screens. |
170 | |||
171 | |||
172 | Implementation details | ||
173 | ====================== | ||
174 | |||
175 | For the interested, here's the code flow which happens inside the kernel | ||
176 | when you use the /dev interface to I2C: | ||
177 | |||
178 | 1* Your program opens /dev/i2c-N and calls ioctl() on it, as described in | ||
179 | section "C example" above. | ||
180 | |||
181 | 2* These open() and ioctl() calls are handled by the i2c-dev kernel | ||
182 | driver: see i2c-dev.c:i2cdev_open() and i2c-dev.c:i2cdev_ioctl(), | ||
183 | respectively. You can think of i2c-dev as a generic I2C chip driver | ||
184 | that can be programmed from user-space. | ||
185 | |||
186 | 3* Some ioctl() calls are for administrative tasks and are handled by | ||
187 | i2c-dev directly. Examples include I2C_SLAVE (set the address of the | ||
188 | device you want to access) and I2C_PEC (enable or disable SMBus error | ||
189 | checking on future transactions.) | ||
190 | |||
191 | 4* Other ioctl() calls are converted to in-kernel function calls by | ||
192 | i2c-dev. Examples include I2C_FUNCS, which queries the I2C adapter | ||
193 | functionality using i2c.h:i2c_get_functionality(), and I2C_SMBUS, which | ||
194 | performs an SMBus transaction using i2c-core.c:i2c_smbus_xfer(). | ||
195 | |||
196 | The i2c-dev driver is responsible for checking all the parameters that | ||
197 | come from user-space for validity. After this point, there is no | ||
198 | difference between these calls that came from user-space through i2c-dev | ||
199 | and calls that would have been performed by kernel I2C chip drivers | ||
200 | directly. This means that I2C bus drivers don't need to implement | ||
201 | anything special to support access from user-space. | ||
202 | |||
203 | 5* These i2c-core.c/i2c.h functions are wrappers to the actual | ||
204 | implementation of your I2C bus driver. Each adapter must declare | ||
205 | callback functions implementing these standard calls. | ||
206 | i2c.h:i2c_get_functionality() calls i2c_adapter.algo->functionality(), | ||
207 | while i2c-core.c:i2c_smbus_xfer() calls either | ||
208 | adapter.algo->smbus_xfer() if it is implemented, or if not, | ||
209 | i2c-core.c:i2c_smbus_xfer_emulated() which in turn calls | ||
210 | i2c_adapter.algo->master_xfer(). | ||
211 | |||
212 | After your I2C bus driver has processed these requests, execution runs | ||
213 | up the call chain, with almost no processing done, except by i2c-dev to | ||
214 | package 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. | |||
109 | S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P | 109 | S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P |
110 | 110 | ||
111 | 111 | ||
112 | SMBus Process Call | 112 | SMBus Process Call: i2c_smbus_process_call() |
113 | ================== | 113 | ============================================= |
114 | 114 | ||
115 | This command selects a device register (through the Comm byte), sends | 115 | This command selects a device register (through the Comm byte), sends |
116 | 16 bits of data to it, and reads 16 bits of data in return. | 116 | 16 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 | |||
621 | be added back later if needed: | 623 | be 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 @@ | |||
1 | Currently, kvm module in EXPERIMENTAL stage on IA64. This means that | 1 | Currently, kvm module is in EXPERIMENTAL stage on IA64. This means that |
2 | interfaces are not stable enough to use. So, plase had better don't run | 2 | interfaces are not stable enough to use. So, please don't run critical |
3 | critical applications in virtual machine. We will try our best to make it | 3 | applications in virtual machine. |
4 | strong in future versions! | 4 | We 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 | ||
7 | This guide is to describe how to enable kvm support for IA-64 systems. | 8 | This 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) { | |||
168 | mkdir $ARGV[0],0777; | 168 | mkdir $ARGV[0],0777; |
169 | $state = 0; | 169 | $state = 0; |
170 | while (<STDIN>) { | 170 | while (<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 | ||
121 | Note kobject_rename does perform any locking or have a solid notion of | ||
122 | what names are valid so the provide must provide their own sanity checking | ||
123 | and serialization. | ||
124 | |||
121 | There is a function called kobject_set_name() but that is legacy cruft and | 125 | There is a function called kobject_set_name() but that is legacy cruft and |
122 | is being removed. If your code needs to call this function, it is | 126 | is being removed. If your code needs to call this function, it is |
123 | incorrect and needs to be fixed. | 127 | incorrect 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 @@ | |||
1 | Hard disk shock protection | ||
2 | ========================== | ||
3 | |||
4 | Author: Elias Oltmanns <eo@nebensachen.de> | ||
5 | Last modified: 2008-10-03 | ||
6 | |||
7 | |||
8 | 0. Contents | ||
9 | ----------- | ||
10 | |||
11 | 1. Intro | ||
12 | 2. The interface | ||
13 | 3. References | ||
14 | 4. CREDITS | ||
15 | |||
16 | |||
17 | 1. Intro | ||
18 | -------- | ||
19 | |||
20 | ATA/ATAPI-7 specifies the IDLE IMMEDIATE command with unload feature. | ||
21 | Issuing this command should cause the drive to switch to idle mode and | ||
22 | unload disk heads. This feature is being used in modern laptops in | ||
23 | conjunction with accelerometers and appropriate software to implement | ||
24 | a shock protection facility. The idea is to stop all I/O operations on | ||
25 | the internal hard drive and park its heads on the ramp when critical | ||
26 | situations are anticipated. The desire to have such a feature | ||
27 | available on GNU/Linux systems has been the original motivation to | ||
28 | implement a generic disk head parking interface in the Linux kernel. | ||
29 | Please note, however, that other components have to be set up on your | ||
30 | system in order to get disk shock protection working (see | ||
31 | section 3. References below for pointers to more information about | ||
32 | that). | ||
33 | |||
34 | |||
35 | 2. The interface | ||
36 | ---------------- | ||
37 | |||
38 | For each ATA device, the kernel exports the file | ||
39 | block/*/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. | ||
42 | Otherwise, writing an integer value to this file will take the heads | ||
43 | of the respective drive off the platter and block all I/O operations | ||
44 | for the specified number of milliseconds. When the timeout expires and | ||
45 | no further disk head park request has been issued in the meantime, | ||
46 | normal operation will be resumed. The maximal value accepted for a | ||
47 | timeout is 30000 milliseconds. Exceeding this limit will return | ||
48 | -EOVERFLOW, but heads will be parked anyway and the timeout will be | ||
49 | set to 30 seconds. However, you can always change a timeout to any | ||
50 | value between 0 and 30000 by issuing a subsequent head park request | ||
51 | before the timeout of the previous one has expired. In particular, the | ||
52 | total timeout can exceed 30 seconds and, more importantly, you can | ||
53 | cancel a previously set timeout and resume normal operation | ||
54 | immediately by specifying a timeout of 0. Values below -2 are rejected | ||
55 | with -EINVAL (see below for the special meaning of -1 and -2). If the | ||
56 | timeout specified for a recent head park request has not yet expired, | ||
57 | reading from /sys/block/*/device/unload_heads will report the number | ||
58 | of milliseconds remaining until normal operation will be resumed; | ||
59 | otherwise, reading the unload_heads attribute will return 0. | ||
60 | |||
61 | For 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 | |||
66 | A simple | ||
67 | |||
68 | # cat /sys/block/sda/device/unload_heads | ||
69 | |||
70 | will show you how many milliseconds are left before normal operation | ||
71 | will be resumed. | ||
72 | |||
73 | A word of caution: The fact that the interface operates on a basis of | ||
74 | milliseconds may raise expectations that cannot be satisfied in | ||
75 | reality. In fact, the ATA specs clearly state that the time for an | ||
76 | unload operation to complete is vendor specific. The hint in ATA-7 | ||
77 | that this will typically be within 500 milliseconds apparently has | ||
78 | been dropped in ATA-8. | ||
79 | |||
80 | There is a technical detail of this implementation that may cause some | ||
81 | confusion and should be discussed here. When a head park request has | ||
82 | been issued to a device successfully, all I/O operations on the | ||
83 | controller port this device is attached to will be deferred. That is | ||
84 | to say, any other device that may be connected to the same port will | ||
85 | be affected too. The only exception is that a subsequent head unload | ||
86 | request to that other device will be executed immediately. Further | ||
87 | operations on that port will be deferred until the timeout specified | ||
88 | for either device on the port has expired. As far as PATA (old style | ||
89 | IDE) configurations are concerned, there can only be two devices | ||
90 | attached to any single port. In SATA world we have port multipliers | ||
91 | which means that a user-issued head parking request to one device may | ||
92 | actually result in stopping I/O to a whole bunch of devices. However, | ||
93 | since this feature is supposed to be used on laptops and does not seem | ||
94 | to be very useful in any other environment, there will be mostly one | ||
95 | device per port. Even if the CD/DVD writer happens to be connected to | ||
96 | the same port as the hard drive, it generally *should* recover just | ||
97 | fine from the occasional buffer under-run incurred by a head park | ||
98 | request to the HD. Actually, when you are using an ide driver rather | ||
99 | than its libata counterpart (i.e. your disk is called /dev/hda | ||
100 | instead of /dev/sda), then parking the heads of one drive (drive X) | ||
101 | will 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 | ||
103 | reset is required to recover from an exception on drive Y that further | ||
104 | I/O operations on that drive (and the reset itself) will be delayed | ||
105 | until drive X is no longer in the parked state. | ||
106 | |||
107 | Finally, there are some hard drives that only comply with an earlier | ||
108 | version of the ATA standard than ATA-7, but do support the unload | ||
109 | feature nonetheless. Unfortunately, there is no safe way Linux can | ||
110 | detect these devices, so you won't be able to write to the | ||
111 | unload_heads attribute. If you know that your device really does | ||
112 | support the unload feature (for instance, because the vendor of your | ||
113 | laptop or the hard drive itself told you so), then you can tell the | ||
114 | kernel to enable the usage of this feature for that drive by writing | ||
115 | the special value -1 to the unload_heads attribute: | ||
116 | |||
117 | # echo -1 > /sys/block/sda/device/unload_heads | ||
118 | |||
119 | will enable the feature for /dev/sda, and giving -2 instead of -1 will | ||
120 | disable it again. | ||
121 | |||
122 | |||
123 | 3. References | ||
124 | ------------- | ||
125 | |||
126 | There are several laptops from different vendors featuring shock | ||
127 | protection capabilities. As manufacturers have refused to support open | ||
128 | source development of the required software components so far, Linux | ||
129 | support for shock protection varies considerably between different | ||
130 | hardware implementations. Ideally, this section should contain a list | ||
131 | of pointers at different projects aiming at an implementation of shock | ||
132 | protection on different systems. Unfortunately, I only know of a | ||
133 | single project which, although still considered experimental, is fit | ||
134 | for use. Please feel free to add projects that have been the victims | ||
135 | of 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 | |||
142 | 4. CREDITS | ||
143 | ---------- | ||
144 | |||
145 | This implementation of disk head parking has been inspired by a patch | ||
146 | originally published by Jon Escombe <lists@dresco.co.uk>. My efforts | ||
147 | to develop an implementation of this feature that is fit to be merged | ||
148 | into mainline have been aided by various kernel developers, in | ||
149 | particular 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 @@ | |||
1 | Copyright (c) 2003-2008 QLogic Corporation | ||
2 | QLogic Linux Networking HBA Driver | ||
3 | |||
4 | This program includes a device driver for Linux 2.6 that may be | ||
5 | distributed with QLogic hardware specific firmware binary file. | ||
6 | You may modify and redistribute the device driver code under the | ||
7 | GNU General Public License as published by the Free Software | ||
8 | Foundation (version 2 or a later version). | ||
9 | |||
10 | You may redistribute the hardware specific firmware binary file | ||
11 | under 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 | |||
26 | REGARDLESS OF WHAT LICENSING MECHANISM IS USED OR APPLICABLE, | ||
27 | THIS PROGRAM IS PROVIDED BY QLOGIC CORPORATION "AS IS'' AND ANY | ||
28 | EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | ||
29 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A | ||
30 | PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR | ||
31 | BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, | ||
32 | EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED | ||
33 | TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, | ||
34 | DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON | ||
35 | ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, | ||
36 | OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | ||
37 | OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE | ||
38 | POSSIBILITY OF SUCH DAMAGE. | ||
39 | |||
40 | USER ACKNOWLEDGES AND AGREES THAT USE OF THIS PROGRAM WILL NOT | ||
41 | CREATE OR GIVE GROUNDS FOR A LICENSE BY IMPLICATION, ESTOPPEL, OR | ||
42 | OTHERWISE IN ANY INTELLECTUAL PROPERTY RIGHTS (PATENT, COPYRIGHT, | ||
43 | TRADE SECRET, MASK WORK, OR OTHER PROPRIETARY RIGHT) EMBODIED IN | ||
44 | ANY OTHER QLOGIC HARDWARE OR SOFTWARE EITHER SOLELY OR IN | ||
45 | COMBINATION 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 | ||
5 | This document was contributed by Cirrus Logic for kernel 2.2.5. This version | 5 | This document was contributed by Cirrus Logic for kernel 2.2.5. This version |
6 | has been updated for 2.3.48 by Andrew Morton <andrewm@uow.edu.au> | 6 | has been updated for 2.3.48 by Andrew Morton. |
7 | 7 | ||
8 | Cirrus make a copy of this driver available at their website, as | 8 | Cirrus make a copy of this driver available at their website, as |
9 | described below. In general, you should use the driver version which | 9 | described below. In general, you should use the driver version which |
@@ -690,7 +690,7 @@ latest drivers and technical publications. | |||
690 | 6.4 Current maintainer | 690 | 6.4 Current maintainer |
691 | 691 | ||
692 | In February 2000 the maintenance of this driver was assumed by Andrew | 692 | In February 2000 the maintenance of this driver was assumed by Andrew |
693 | Morton <akpm@zip.com.au> | 693 | Morton. |
694 | 694 | ||
695 | 6.5 Kernel module parameters | 695 | 6.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 | |||
24 | device is still operational. netdev->queue_lock is still used when the device | 24 | device is still operational. netdev->queue_lock is still used when the device |
25 | comes online or when it's completely shut down (unregister_netdev(), etc.). | 25 | comes online or when it's completely shut down (unregister_netdev(), etc.). |
26 | 26 | ||
27 | Author: Peter P. Waskiewicz Jr. <peter.p.waskiewicz.jr@intel.com> | 27 | |
28 | Section 2: Qdisc support for multiqueue devices | ||
29 | |||
30 | ----------------------------------------------- | ||
31 | |||
32 | Currently two qdiscs are optimized for multiqueue devices. The first is the | ||
33 | default pfifo_fast qdisc. This qdisc supports one qdisc per hardware queue. | ||
34 | A new round-robin qdisc, sch_multiq also supports multiple hardware queues. The | ||
35 | qdisc is responsible for classifying the skb's and then directing the skb's to | ||
36 | bands and queues based on the value in skb->queue_mapping. Use this field in | ||
37 | the base driver to determine which queue to send the skb to. | ||
38 | |||
39 | sch_multiq has been added for hardware that wishes to avoid head-of-line | ||
40 | blocking. It will cycle though the bands and verify that the hardware queue | ||
41 | associated with the band is not stopped prior to dequeuing a packet. | ||
42 | |||
43 | On qdisc load, the number of bands is based on the number of queues on the | ||
44 | hardware. Once the association is made, any skb with skb->queue_mapping set, | ||
45 | will be queued to the band associated with the hardware queue. | ||
46 | |||
47 | |||
48 | Section 3: Brief howto using MULTIQ for multiqueue devices | ||
49 | --------------------------------------------------------------- | ||
50 | |||
51 | The userspace command 'tc,' part of the iproute2 package, is used to configure | ||
52 | qdiscs. To add the MULTIQ qdisc to your network device, assuming the device | ||
53 | is called eth0, run the following command: | ||
54 | |||
55 | # tc qdisc add dev eth0 root handle 1: multiq | ||
56 | |||
57 | The qdisc will allocate the number of bands to equal the number of queues that | ||
58 | the device reports, and bring the qdisc online. Assuming eth0 has 4 Tx | ||
59 | queues, the band mapping would look like: | ||
60 | |||
61 | band 0 => queue 0 | ||
62 | band 1 => queue 1 | ||
63 | band 2 => queue 2 | ||
64 | band 3 => queue 3 | ||
65 | |||
66 | Traffic will begin flowing through each queue based on either the simple_tx_hash | ||
67 | function or based on netdev->select_queue() if you have it defined. | ||
68 | |||
69 | The behavior of tc filters remains the same. However a new tc action, | ||
70 | skbedit, has been added. Assuming you wanted to route all traffic to a | ||
71 | specific host, for example 192.168.0.3, through a specific queue you could use | ||
72 | this action and establish a filter such as: | ||
73 | |||
74 | tc 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 | |||
78 | Author: Alexander Duyck <alexander.h.duyck@intel.com> | ||
79 | Original 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 @@ | |||
1 | Linux Phonet protocol family | ||
2 | ============================ | ||
3 | |||
4 | Introduction | ||
5 | ------------ | ||
6 | |||
7 | Phonet is a packet protocol used by Nokia cellular modems for both IPC | ||
8 | and RPC. With the Linux Phonet socket family, Linux host processes can | ||
9 | receive and send messages from/to the modem, or any other external | ||
10 | device attached to the modem. The modem takes care of routing. | ||
11 | |||
12 | Phonet packets can be exchanged through various hardware connections | ||
13 | depending 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 | |||
21 | Packets format | ||
22 | -------------- | ||
23 | |||
24 | Phonet 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 | |||
36 | On Linux, the link-layer header includes the pn_media byte (see below). | ||
37 | The next 7 bytes are part of the network-layer header. | ||
38 | |||
39 | The device ID is split: the 6 higher-order bits consitute the device | ||
40 | address, while the 2 lower-order bits are used for multiplexing, as are | ||
41 | the 8-bit object identifiers. As such, Phonet can be considered as a | ||
42 | network layer with 6 bits of address space and 10 bits for transport | ||
43 | protocol (much like port numbers in IP world). | ||
44 | |||
45 | The modem always has address number zero. All other device have a their | ||
46 | own 6-bit address. | ||
47 | |||
48 | |||
49 | Link layer | ||
50 | ---------- | ||
51 | |||
52 | Phonet links are always point-to-point links. The link layer header | ||
53 | consists of a single Phonet media type byte. It uniquely identifies the | ||
54 | link through which the packet is transmitted, from the modem's | ||
55 | perspective. Each Phonet network device shall prepend and set the media | ||
56 | type byte as appropriate. For convenience, a common phonet_header_ops | ||
57 | link-layer header operations structure is provided. It sets the | ||
58 | media type according to the network device hardware address. | ||
59 | |||
60 | Linux Phonet network interfaces support a dedicated link layer packets | ||
61 | type (ETH_P_PHONET) which is out of the Ethernet type range. They can | ||
62 | only send and receive Phonet packets. | ||
63 | |||
64 | The virtual TUN tunnel device driver can also be used for Phonet. This | ||
65 | requires IFF_TUN mode, _without_ the IFF_NO_PI flag. In this case, | ||
66 | there is no link-layer header, so there is no Phonet media type byte. | ||
67 | |||
68 | Note that Phonet interfaces are not allowed to re-order packets, so | ||
69 | only the (default) Linux FIFO qdisc should be used with them. | ||
70 | |||
71 | |||
72 | Network layer | ||
73 | ------------- | ||
74 | |||
75 | The 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 | |||
85 | The resource field is only used when sending and receiving; | ||
86 | It is ignored by bind() and getsockname(). | ||
87 | |||
88 | |||
89 | Low-level datagram protocol | ||
90 | --------------------------- | ||
91 | |||
92 | Applications can send Phonet messages using the Phonet datagram socket | ||
93 | protocol from the PF_PHONET family. Each socket is bound to one of the | ||
94 | 2^10 object IDs available, and can send and receive packets with any | ||
95 | other 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 | |||
110 | This protocol follows the SOCK_DGRAM connection-less semantics. | ||
111 | However, connect() and getpeername() are not supported, as they did | ||
112 | not seem useful with Phonet usages (could be added easily). | ||
113 | |||
114 | |||
115 | Phonet Pipe protocol | ||
116 | -------------------- | ||
117 | |||
118 | The Phonet Pipe protocol is a simple sequenced packets protocol | ||
119 | with end-to-end congestion control. It uses the passive listening | ||
120 | socket paradigm. The listening socket is bound to an unique free object | ||
121 | ID. Each listening socket can handle up to 255 simultaneous | ||
122 | connections, 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 | |||
141 | Connections are established between two endpoints by a "third party" | ||
142 | application. This means that both endpoints are passive; so connect() | ||
143 | is not possible. | ||
144 | |||
145 | WARNING: | ||
146 | When polling a connected pipe socket for writability, there is an | ||
147 | intrinsic race condition whereby writability might be lost between the | ||
148 | polling and the writing system calls. In this case, the socket will | ||
149 | block until write becomes possible again, unless non-blocking mode | ||
150 | is enabled. | ||
151 | |||
152 | |||
153 | The 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 | |||
169 | Authors | ||
170 | ------- | ||
171 | |||
172 | Linux Phonet was initially written by Sakari Ailus. | ||
173 | Other contributors include Mikä Liljeberg, Andras Domokos, | ||
174 | Carlos Chinea and Rémi Denis-Courmont. | ||
175 | Copyright (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 @@ | |||
1 | Linux wireless regulatory documentation | ||
2 | --------------------------------------- | ||
3 | |||
4 | This document gives a brief review over how the Linux wireless | ||
5 | regulatory infrastructure works. | ||
6 | |||
7 | More up to date information can be obtained at the project's web page: | ||
8 | |||
9 | http://wireless.kernel.org/en/developers/Regulatory | ||
10 | |||
11 | Keeping regulatory domains in userspace | ||
12 | --------------------------------------- | ||
13 | |||
14 | Due to the dynamic nature of regulatory domains we keep them | ||
15 | in userspace and provide a framework for userspace to upload | ||
16 | to the kernel one regulatory domain to be used as the central | ||
17 | core regulatory domain all wireless devices should adhere to. | ||
18 | |||
19 | How to get regulatory domains to the kernel | ||
20 | ------------------------------------------- | ||
21 | |||
22 | Userspace gets a regulatory domain in the kernel by having | ||
23 | a userspace agent build it and send it via nl80211. Only | ||
24 | expected regulatory domains will be respected by the kernel. | ||
25 | |||
26 | A currently available userspace agent which can accomplish this | ||
27 | is CRDA - central regulatory domain agent. Its documented here: | ||
28 | |||
29 | http://wireless.kernel.org/en/developers/Regulatory/CRDA | ||
30 | |||
31 | Essentially the kernel will send a udev event when it knows | ||
32 | it needs a new regulatory domain. A udev rule can be put in place | ||
33 | to trigger crda to send the respective regulatory domain for a | ||
34 | specific ISO/IEC 3166 alpha2. | ||
35 | |||
36 | Below is an example udev rule which can be used: | ||
37 | |||
38 | # Example file, should be put in /etc/udev/rules.d/regulatory.rules | ||
39 | KERNEL=="regulatory*", ACTION=="change", SUBSYSTEM=="platform", RUN+="/sbin/crda" | ||
40 | |||
41 | The alpha2 is passed as an environment variable under the variable COUNTRY. | ||
42 | |||
43 | Who asks for regulatory domains? | ||
44 | -------------------------------- | ||
45 | |||
46 | * Users | ||
47 | |||
48 | Users can use iw: | ||
49 | |||
50 | http://wireless.kernel.org/en/users/Documentation/iw | ||
51 | |||
52 | An example: | ||
53 | |||
54 | # set regulatory domain to "Costa Rica" | ||
55 | iw reg set CR | ||
56 | |||
57 | This will request the kernel to set the regulatory domain to | ||
58 | the specificied alpha2. The kernel in turn will then ask userspace | ||
59 | to provide a regulatory domain for the alpha2 specified by the user | ||
60 | by sending a uevent. | ||
61 | |||
62 | * Wireless subsystems for Country Information elements | ||
63 | |||
64 | The kernel will send a uevent to inform userspace a new | ||
65 | regulatory domain is required. More on this to be added | ||
66 | as its integration is added. | ||
67 | |||
68 | * Drivers | ||
69 | |||
70 | If drivers determine they need a specific regulatory domain | ||
71 | set they can inform the wireless core using regulatory_hint(). | ||
72 | They have two options -- they either provide an alpha2 so that | ||
73 | crda can provide back a regulatory domain for that country or | ||
74 | they can build their own regulatory domain based on internal | ||
75 | custom knowledge so the wireless core can respect it. | ||
76 | |||
77 | *Most* drivers will rely on the first mechanism of providing a | ||
78 | regulatory hint with an alpha2. For these drivers there is an additional | ||
79 | check that can be used to ensure compliance based on custom EEPROM | ||
80 | regulatory data. This additional check can be used by drivers by | ||
81 | registering on its struct wiphy a reg_notifier() callback. This notifier | ||
82 | is called when the core's regulatory domain has been changed. The driver | ||
83 | can 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 | ||
85 | internal EEPROM data. Devices drivers wishing to be capable of world | ||
86 | roaming should use this callback. More on world roaming will be | ||
87 | added to this document when its support is enabled. | ||
88 | |||
89 | Device drivers who provide their own built regulatory domain | ||
90 | do not need a callback as the channels registered by them are | ||
91 | the only ones that will be allowed and therefore *additional* | ||
92 | cannels cannot be enabled. | ||
93 | |||
94 | Example code - drivers hinting an alpha2: | ||
95 | ------------------------------------------ | ||
96 | |||
97 | This example comes from the zd1211rw device driver. You can start | ||
98 | by having a mapping of your device's EEPROM country/regulatory | ||
99 | domain value to to a specific alpha2 as follows: | ||
100 | |||
101 | static 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 | |||
110 | Then you can define a routine to map your read EEPROM value to an alpha2, | ||
111 | as follows: | ||
112 | |||
113 | static 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 = ®_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 | |||
128 | Lastly, you can then hint to the core of your discovered alpha2, if a match | ||
129 | was found. You need to do this after you have registered your wiphy. You | ||
130 | are 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 | |||
136 | Example code - drivers providing a built in regulatory domain: | ||
137 | -------------------------------------------------------------- | ||
138 | |||
139 | If you have regulatory information you can obtain from your | ||
140 | driver and you *need* to use this we let you build a regulatory domain | ||
141 | structure and pass it to the wireless core. To do this you should | ||
142 | kmalloc() a structure big enough to hold your regulatory domain | ||
143 | structure and you should then fill it with your data. Finally you simply | ||
144 | call regulatory_hint() with the regulatory domain structure in it. | ||
145 | |||
146 | Bellow is a simple example, with a regulatory domain cached using the stack. | ||
147 | Your implementation may vary (read EEPROM cache instead, for example). | ||
148 | |||
149 | Example cache of some regulatory domain | ||
150 | |||
151 | struct 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 | |||
168 | Then 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 @@ | |||
1 | Transparent proxy support | ||
2 | ========================= | ||
3 | |||
4 | This feature adds Linux 2.2-like transparent proxy support to current kernels. | ||
5 | To use it, enable NETFILTER_TPROXY, the socket match and the TPROXY target in | ||
6 | your kernel config. You will need policy routing too, so be sure to enable that | ||
7 | as well. | ||
8 | |||
9 | |||
10 | 1. Making non-local sockets work | ||
11 | ================================ | ||
12 | |||
13 | The idea is that you identify packets with destination address matching a local | ||
14 | socket on your box, set the packet mark to a certain value, and then match on that | ||
15 | value 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 | |||
25 | Because of certain restrictions in the IPv4 routing output code you'll have to | ||
26 | modify your application to allow it to send datagrams _from_ non-local IP | ||
27 | addresses. All you have to do is enable the (SOL_IP, IP_TRANSPARENT) socket | ||
28 | option before calling bind: | ||
29 | |||
30 | fd = socket(AF_INET, SOCK_STREAM, 0); | ||
31 | /* - 8< -*/ | ||
32 | int value = 1; | ||
33 | setsockopt(fd, SOL_IP, IP_TRANSPARENT, &value, sizeof(value)); | ||
34 | /* - 8< -*/ | ||
35 | name.sin_family = AF_INET; | ||
36 | name.sin_port = htons(0xCAFE); | ||
37 | name.sin_addr.s_addr = htonl(0xDEADBEEF); | ||
38 | bind(fd, &name, sizeof(name)); | ||
39 | |||
40 | A trivial patch for netcat is available here: | ||
41 | http://people.netfilter.org/hidden/tproxy/netcat-ip_transparent-support.patch | ||
42 | |||
43 | |||
44 | 2. Redirecting traffic | ||
45 | ====================== | ||
46 | |||
47 | Transparent proxying often involves "intercepting" traffic on a router. This is | ||
48 | usually done with the iptables REDIRECT target; however, there are serious | ||
49 | limitations of that method. One of the major issues is that it actually | ||
50 | modifies the packets to change the destination address -- which might not be | ||
51 | acceptable in certain situations. (Think of proxying UDP for example: you won't | ||
52 | be able to find out the original destination address. Even in case of TCP | ||
53 | getting the original destination address is racy.) | ||
54 | |||
55 | The 'TPROXY' target provides similar functionality without relying on NAT. Simply | ||
56 | add 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 | |||
61 | Note that for this to work you'll have to modify the proxy to enable (SOL_IP, | ||
62 | IP_TRANSPARENT) for the listening socket. | ||
63 | |||
64 | |||
65 | 3. Iptables extensions | ||
66 | ====================== | ||
67 | |||
68 | To use tproxy you'll need to have the 'socket' and 'TPROXY' modules | ||
69 | compiled for iptables. A patched version of iptables is available | ||
70 | here: http://git.balabit.hu/?p=bazsi/iptables-tproxy.git | ||
71 | |||
72 | |||
73 | 4. Application support | ||
74 | ====================== | ||
75 | |||
76 | 4.1. Squid | ||
77 | ---------- | ||
78 | |||
79 | Squid 3.HEAD has support built-in. To use it, pass | ||
80 | '--enable-linux-netfilter' to configure and set the 'tproxy' option on | ||
81 | the HTTP listener you redirect traffic to with the TPROXY iptables | ||
82 | target. | ||
83 | |||
84 | For more information please consult the following page on the Squid | ||
85 | wiki: 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 @@ | |||
1 | Documentation/networking/vortex.txt | 1 | Documentation/networking/vortex.txt |
2 | Andrew Morton <andrewm@uow.edu.au> | 2 | Andrew Morton |
3 | 30 April 2000 | 3 | 30 April 2000 |
4 | 4 | ||
5 | 5 | ||
@@ -11,7 +11,7 @@ The driver was written by Donald Becker <becker@scyld.com> | |||
11 | Don is no longer the prime maintainer of this version of the driver. | 11 | Don is no longer the prime maintainer of this version of the driver. |
12 | Please report problems to one or more of: | 12 | Please 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 | ||
308 | Driver updates and a detailed changelog for the modifications which | ||
309 | were 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 | ||
314 | Autonegotiation notes | 309 | Autonegotiation 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 @@ | |||
1 | This file details changes in 2.6 which affect PCMCIA card driver authors: | 1 | This 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 | ||
4 | The regulator machine driver interface is intended for board/machine specific | 4 | The regulator machine driver interface is intended for board/machine specific |
5 | initialisation code to configure the regulator subsystem. Typical things that | 5 | initialisation code to configure the regulator subsystem. |
6 | machine 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 | |||
14 | 1. Regulator -> device mapping | ||
15 | ============================== | ||
16 | Consider the following machine :- | 7 | Consider 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 | ||
22 | The drivers for consumers A & B must be mapped to the correct regulator in | 13 | The drivers for consumers A & B must be mapped to the correct regulator in |
23 | order to control their power supply. This mapping can be achieved in machine | 14 | order to control their power supply. This mapping can be achieved in machine |
24 | initialisation code by calling :- | 15 | initialisation code by creating a struct regulator_consumer_supply for |
16 | each regulator. | ||
17 | |||
18 | struct regulator_consumer_supply { | ||
19 | struct device *dev; /* consumer */ | ||
20 | const char *supply; /* consumer supply - e.g. "vcc" */ | ||
21 | }; | ||
25 | 22 | ||
26 | int regulator_set_device_supply(const char *regulator, struct device *dev, | 23 | e.g. for the machine above |
27 | const char *supply); | ||
28 | 24 | ||
29 | and is shown with the following code :- | 25 | static struct regulator_consumer_supply regulator1_consumers[] = { |
26 | { | ||
27 | .dev = &platform_consumerB_device.dev, | ||
28 | .supply = "Vcc", | ||
29 | },}; | ||
30 | 30 | ||
31 | regulator_set_device_supply("Regulator-1", devB, "Vcc"); | 31 | static struct regulator_consumer_supply regulator2_consumers[] = { |
32 | regulator_set_device_supply("Regulator-2", devA, "Vcc"); | 32 | { |
33 | .dev = &platform_consumerA_device.dev, | ||
34 | .supply = "Vcc", | ||
35 | },}; | ||
33 | 36 | ||
34 | This maps Regulator-1 to the 'Vcc' supply for Consumer B and maps Regulator-2 | 37 | This maps Regulator-1 to the 'Vcc' supply for Consumer B and maps Regulator-2 |
35 | to the 'Vcc' supply for Consumer A. | 38 | to the 'Vcc' supply for Consumer A. |
36 | 39 | ||
37 | 40 | Constraints can now be registered by defining a struct regulator_init_data | |
38 | 2. Regulator supply configuration. | 41 | for each regulator power domain. This structure also maps the consumers |
39 | ================================== | 42 | to their supply regulator :- |
40 | Consider the following machine (again) :- | 43 | |
41 | 44 | static 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 | ||
46 | Regulator-1 supplies power to Regulator-2. This relationship must be registered | 54 | Regulator-1 supplies power to Regulator-2. This relationship must be registered |
47 | with the core so that Regulator-1 is also enabled when Consumer A enables it's | 55 | with the core so that Regulator-1 is also enabled when Consumer A enables it's |
48 | supply (Regulator-2). | 56 | supply (Regulator-2). The supply regulator is set by the supply_regulator_dev |
49 | 57 | field below:- | |
50 | This relationship can be register with the core via :- | 58 | |
51 | 59 | static struct regulator_init_data regulator2_data = { | |
52 | int regulator_set_supply(const char *regulator, const char *regulator_supply); | 60 | .supply_regulator_dev = &platform_regulator1_device.dev, |
53 | 61 | .constraints = { | |
54 | In this example we would use the following code :- | 62 | .min_uV = 1800000, |
55 | 63 | .max_uV = 2000000, | |
56 | regulator_set_supply("Regulator-2", "Regulator-1"); | 64 | .valid_ops_mask = REGULATOR_CHANGE_VOLTAGE, |
57 | 65 | .valid_modes_mask = REGULATOR_MODE_NORMAL, | |
58 | Relationships can be queried by calling :- | 66 | }, |
59 | 67 | .num_consumer_supplies = ARRAY_SIZE(regulator2_consumers), | |
60 | const char *regulator_get_supply(const char *regulator); | 68 | .consumer_supplies = regulator2_consumers, |
61 | |||
62 | |||
63 | 3. Power Domain constraint setting. | ||
64 | =================================== | ||
65 | Each power domain within a system has physical constraints on voltage and | ||
66 | current. This must be defined in software so that the power domain is always | ||
67 | operated within specifications. | ||
68 | |||
69 | Consider the following machine (again) :- | ||
70 | |||
71 | Regulator-1 -+-> Regulator-2 --> [Consumer A @ 1.8 - 2.0V] | ||
72 | | | ||
73 | +-> [Consumer B @ 3.3V] | ||
74 | |||
75 | This gives us two regulators and two power domains: | ||
76 | |||
77 | Domain 1: Regulator-2, Consumer B. | ||
78 | Domain 2: Consumer A. | ||
79 | |||
80 | Constraints can be registered by calling :- | ||
81 | |||
82 | int regulator_set_platform_constraints(const char *regulator, | ||
83 | struct regulation_constraints *constraints); | ||
84 | |||
85 | The example is defined as follows :- | ||
86 | |||
87 | struct regulation_constraints domain_1 = { | ||
88 | .min_uV = 3300000, | ||
89 | .max_uV = 3300000, | ||
90 | .valid_modes_mask = REGULATOR_MODE_NORMAL, | ||
91 | }; | 69 | }; |
92 | 70 | ||
93 | struct regulation_constraints domain_2 = { | 71 | Finally the regulator devices must be registered in the usual manner. |
94 | .min_uV = 1800000, | 72 | |
95 | .max_uV = 2000000, | 73 | static 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 = ®ulator1_data, | ||
79 | }, | ||
80 | }, | ||
81 | { | ||
82 | .name = "regulator", | ||
83 | .id = DCDC_2, | ||
84 | .dev = { | ||
85 | .platform_data = ®ulator2_data, | ||
86 | }, | ||
87 | }, | ||
98 | }; | 88 | }; |
89 | /* register regulator 1 device */ | ||
90 | platform_device_register(&wm8350_regulator_devices[0]); | ||
99 | 91 | ||
100 | regulator_set_platform_constraints("Regulator-1", &domain_1); | 92 | /* register regulator 2 device */ |
101 | regulator_set_platform_constraints("Regulator-2", &domain_2); | 93 | platform_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 | ||
11 | Drivers can register a regulator by calling :- | 11 | Drivers can register a regulator by calling :- |
12 | 12 | ||
13 | struct regulator_dev *regulator_register(struct regulator_desc *regulator_desc, | 13 | struct regulator_dev *regulator_register(struct device *dev, |
14 | void *reg_data); | 14 | struct regulator_desc *regulator_desc); |
15 | 15 | ||
16 | This will register the regulators capabilities and operations the regulator | 16 | This will register the regulators capabilities and operations to the regulator |
17 | core. The core does not touch reg_data (private to regulator driver). | 17 | core. |
18 | 18 | ||
19 | Regulators can be unregistered by calling :- | 19 | Regulators 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 | |||
54 | that "radeonfb" simply cannot resume that device - it tries to set the | 54 | that "radeonfb" simply cannot resume that device - it tries to set the |
55 | PLL's, and it just _hangs_. Using the regular VGA console and letting X | 55 | PLL's, and it just _hangs_. Using the regular VGA console and letting X |
56 | resume it instead works fine. | 56 | resume it instead works fine. |
57 | |||
58 | NOTE | ||
59 | ==== | ||
60 | pm_trace uses the system's Real Time Clock (RTC) to save the magic number. | ||
61 | Reason for this is that the RTC is the only reliably available piece of | ||
62 | hardware during resume operations where a value can be set that will | ||
63 | survive a reboot. | ||
64 | |||
65 | Consequence is that after a resume (even if it is successful) your system | ||
66 | clock will have a value corresponding to the magic mumber instead of the | ||
67 | correct date/time! It is therefore advisable to use a program like ntp-date | ||
68 | or rdate to reset the correct date/time from an external time source when | ||
69 | using this trace option. | ||
70 | |||
71 | As the clock keeps ticking it is also essential that the reboot is done | ||
72 | quickly after the resume failure. The trace option does not use the seconds | ||
73 | or the low order bits of the minutes of the RTC, but a too long delay will | ||
74 | corrupt 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 |
19 | mpc52xx-device-tree-bindings.txt | 19 | mpc52xx-device-tree-bindings.txt |
20 | - MPC5200 Device Tree Bindings | 20 | - MPC5200 Device Tree Bindings |
21 | ppc_htab.txt | ||
22 | - info about the Linux/PPC /proc/ppc_htab entry | ||
23 | smp.txt | ||
24 | - use and state info about Linux/PPC on MP machines | ||
25 | sound.txt | 21 | sound.txt |
26 | - info on sound support under Linux/PPC | 22 | - info on sound support under Linux/PPC |
27 | zImage_layout.txt | 23 | zImage_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 | |||
3 | Freescale 83xx and 512x SOCs include the same pci bridge core. | ||
4 | |||
5 | 83xx/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 | |||
10 | Example (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 @@ | |||
1 | GPIO controllers on MPC8xxx SoCs | ||
2 | |||
3 | This is for the non-QE/CPM/GUTs GPIO controllers as found on | ||
4 | 8349, 8572, 8610 and compatible. | ||
5 | |||
6 | Every GPIO controller node must have #gpio-cells property defined, | ||
7 | this information will be used to translate gpio-specifiers. | ||
8 | |||
9 | Required 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 | |||
19 | Example 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 | |||
39 | See booting-without-of.txt for details of how to specify GPIO | ||
40 | information 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 | |||
129 | Note 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 | ||
131 | driver (fsldma). Any DMA channel used by fsldma cannot be used by another | ||
132 | DMA driver, such as the SSI sound drivers for the MPC8610. Therefore, any DMA | ||
133 | channel 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 | ||
135 | example, the compatible property should be "fsl,ssi-dma-channel". See ssi.txt | ||
136 | for 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 | ||
28 | Optional properties: | 34 | Optional 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: | |||
36 | Child 'codec' node optional properties: | 42 | Child '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 | |||
46 | Notes on fsl,playback-dma and fsl,capture-dma: | ||
47 | |||
48 | On SOCs that have an SSI, specific DMA channels are hard-wired for playback | ||
49 | and capture. On the MPC8610, for example, SSI1 must use DMA channel 0 for | ||
50 | playback and DMA channel 1 for capture. SSI2 must use DMA channel 2 for | ||
51 | playback and DMA channel 3 for capture. The developer can choose which | ||
52 | DMA controller to use, but the channels themselves are hard-wired. The | ||
53 | purpose of these two properties is to represent this hardware design. | ||
54 | |||
55 | The 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 | ||
60 | drivers (fsldma) will attempt to use them, and it will conflict with the | ||
61 | sound 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 | |||
4 | This document and the related code was written by me (Cort Dougan), please | ||
5 | email me (cort@fsmlabs.com) if you have questions, comments or corrections. | ||
6 | |||
7 | Last Change: 2.16.98 | ||
8 | |||
9 | This entry in the proc directory is readable by all users but only | ||
10 | writable by root. | ||
11 | |||
12 | The ppc_htab interface is a user level way of accessing the | ||
13 | performance monitoring registers as well as providing information | ||
14 | about the PTE hash table. | ||
15 | |||
16 | 1. 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 | |||
55 | 2. 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 | |||
115 | 3. 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 | |||
4 | This document and the related code was written by me | ||
5 | (Cort Dougan, cort@fsmlabs.com) please email me if you have questions, | ||
6 | comments or corrections. | ||
7 | |||
8 | Last Change: 3.31.99 | ||
9 | |||
10 | If you want to help by writing code or testing different hardware please | ||
11 | email me! | ||
12 | |||
13 | 1. 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 | |||
341 | 3.1 Guidelines for wireless device drivers | 341 | 3.1 Guidelines for wireless device drivers |
342 | ------------------------------------------ | 342 | ------------------------------------------ |
343 | 343 | ||
344 | (in this text, rfkill->foo means the foo field of struct rfkill). | ||
345 | |||
344 | 1. Each independent transmitter in a wireless device (usually there is only one | 346 | 1. Each independent transmitter in a wireless device (usually there is only one |
345 | transmitter per device) should have a SINGLE rfkill class attached to it. | 347 | transmitter 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, | |||
363 | when possible) the overall transmitter rfkill state, not of a particular rfkill | 365 | when possible) the overall transmitter rfkill state, not of a particular rfkill |
364 | line. | 366 | line. |
365 | 367 | ||
366 | 5. During suspend, the rfkill class will attempt to soft-block the radio | 368 | 5. The wireless device driver MUST NOT leave the transmitter enabled during |
367 | through a call to rfkill->toggle_radio, and will try to restore its previous | 369 | suspend and hibernation unless: |
368 | state during resume. After a rfkill class is suspended, it will *not* call | 370 | |
369 | rfkill->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 | |||
376 | AND | ||
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 | |||
382 | In other words, there is absolutely no allowed scenario where a driver can | ||
383 | automatically take action to unblock a rfkill controller (obviously, this deals | ||
384 | with scenarios where soft-blocking or both soft and hard blocking is happening. | ||
385 | Scenarios where hardware rfkill lines are the only ones blocking the | ||
386 | transmitter are outside of this rule, since the wireless device driver does not | ||
387 | control its input hardware rfkill lines in the first place). | ||
388 | |||
389 | 6. During resume, rfkill will try to restore its previous state. | ||
390 | |||
391 | 7. After a rfkill class is suspended, it will *not* call rfkill->toggle_radio | ||
392 | until it is resumed. | ||
393 | |||
370 | 394 | ||
371 | Example of a WLAN wireless driver connected to the rfkill subsystem: | 395 | Example 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 | ||
2 | This is the CFS scheduler. | ||
3 | |||
4 | 80% of CFS's design can be summed up in a single sentence: CFS basically | ||
5 | models an "ideal, precise multi-tasking CPU" on real hardware. | ||
6 | |||
7 | "Ideal multi-tasking CPU" is a (non-existent :-)) CPU that has 100% | ||
8 | physical power and which can run each task at precise equal speed, in | ||
9 | parallel, each at 1/nr_running speed. For example: if there are 2 tasks | ||
10 | running then it runs each at 50% physical power - totally in parallel. | ||
11 | |||
12 | On real hardware, we can run only a single task at once, so while that | ||
13 | one task runs, the other tasks that are waiting for the CPU are at a | ||
14 | disadvantage - the current task gets an unfair amount of CPU time. In | ||
15 | CFS this fairness imbalance is expressed and tracked via the per-task | ||
16 | p->wait_runtime (nanosec-unit) value. "wait_runtime" is the amount of | ||
17 | time the task should now run on the CPU for it to become completely fair | ||
18 | and 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 | |||
24 | CFS's task picking logic is based on this p->wait_runtime value and it | ||
25 | is thus very simple: it always tries to run the task with the largest | ||
26 | p->wait_runtime value. In other words, CFS tries to run the task with | ||
27 | the 'gravest need' for more CPU time. So CFS always tries to split up | ||
28 | CPU time between runnable tasks as close to 'ideal multitasking | ||
29 | hardware' as possible. | ||
30 | |||
31 | Most of the rest of CFS's design just falls out of this really simple | ||
32 | concept, with a few add-on embellishments like nice levels, | ||
33 | multiprocessing and various algorithm variants to recognize sleepers. | ||
34 | |||
35 | In practice it works like this: the system runs a task a bit, and when | ||
36 | the 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 | ||
38 | is deducted from p->wait_runtime. [minus the 'fair share' it would have | ||
39 | gotten anyway]. Once p->wait_runtime gets low enough so that another | ||
40 | task becomes the 'leftmost task' of the time-ordered rbtree it maintains | ||
41 | (plus a small amount of 'granularity' distance relative to the leftmost | ||
42 | task so that we do not over-schedule tasks and trash the cache) then the | ||
43 | new leftmost task is picked and the current task is preempted. | ||
44 | |||
45 | The rq->fair_clock value tracks the 'CPU time a runnable task would have | ||
46 | fairly gotten, had it been runnable during that time'. So by using | ||
47 | rq->fair_clock values we can accurately timestamp and measure the | ||
48 | 'expected CPU time' a task should have gotten. All runnable tasks are | ||
49 | sorted in the rbtree by the "rq->fair_clock - p->wait_runtime" key, and | ||
50 | CFS picks the 'leftmost' task and sticks to it. As the system progresses | ||
51 | forwards, newly woken tasks are put into the tree more and more to the | ||
52 | right - 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 | ||
54 | time. | ||
55 | |||
56 | Some 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 | |||
121 | Group scheduler extension to CFS | ||
122 | ================================ | ||
123 | |||
124 | Normally the scheduler operates on individual tasks and strives to provide | ||
125 | fair CPU time to each task. Sometimes, it may be desirable to group tasks | ||
126 | and provide fair CPU time to each such task group. For example, it may | ||
127 | be desirable to first provide fair CPU time to each user on the system | ||
128 | and then to each task belonging to a user. | ||
129 | |||
130 | CONFIG_FAIR_GROUP_SCHED strives to achieve exactly that. It lets | ||
131 | SCHED_NORMAL/BATCH tasks be be grouped and divides CPU time fairly among such | ||
132 | groups. At present, there are two (mutually exclusive) mechanisms to group | ||
133 | tasks 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 | ||
143 | Only one of these options to group tasks can be chosen and not both. | 6 | 1. OVERVIEW |
7 | |||
8 | CFS stands for "Completely Fair Scheduler," and is the new "desktop" process | ||
9 | scheduler implemented by Ingo Molnar and merged in Linux 2.6.23. It is the | ||
10 | replacement for the previous vanilla scheduler's SCHED_OTHER interactivity | ||
11 | code. | ||
12 | |||
13 | 80% of CFS's design can be summed up in a single sentence: CFS basically models | ||
14 | an "ideal, precise multi-tasking CPU" on real hardware. | ||
15 | |||
16 | "Ideal multi-tasking CPU" is a (non-existent :-)) CPU that has 100% physical | ||
17 | power and which can run each task at precise equal speed, in parallel, each at | ||
18 | 1/nr_running speed. For example: if there are 2 tasks running, then it runs | ||
19 | each at 50% physical power --- i.e., actually in parallel. | ||
20 | |||
21 | On real hardware, we can run only a single task at once, so we have to | ||
22 | introduce the concept of "virtual runtime." The virtual runtime of a task | ||
23 | specifies when its next timeslice would start execution on the ideal | ||
24 | multi-tasking CPU described above. In practice, the virtual runtime of a task | ||
25 | is its actual runtime normalized to the total number of running tasks. | ||
26 | |||
27 | |||
28 | |||
29 | 2. FEW IMPLEMENTATION DETAILS | ||
30 | |||
31 | In CFS the virtual runtime is expressed and tracked via the per-task | ||
32 | p->se.vruntime (nanosec-unit) value. This way, it's possible to accurately | ||
33 | timestamp 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 | |||
39 | CFS's task picking logic is based on this p->se.vruntime value and it is thus | ||
40 | very simple: it always tries to run the task with the smallest p->se.vruntime | ||
41 | value (i.e., the task which executed least so far). CFS always tries to split | ||
42 | up CPU time between runnable tasks as close to "ideal multitasking hardware" as | ||
43 | possible. | ||
44 | |||
45 | Most of the rest of CFS's design just falls out of this really simple concept, | ||
46 | with a few add-on embellishments like nice levels, multiprocessing and various | ||
47 | algorithm variants to recognize sleepers. | ||
48 | |||
49 | |||
50 | |||
51 | 3. THE RBTREE | ||
52 | |||
53 | CFS's design is quite radical: it does not use the old data structures for the | ||
54 | runqueues, but it uses a time-ordered rbtree to build a "timeline" of future | ||
55 | task execution, and thus has no "array switch" artifacts (by which both the | ||
56 | previous vanilla scheduler and RSDL/SD are affected). | ||
57 | |||
58 | CFS also maintains the rq->cfs.min_vruntime value, which is a monotonic | ||
59 | increasing value tracking the smallest vruntime among all tasks in the | ||
60 | runqueue. The total amount of work done by the system is tracked using | ||
61 | min_vruntime; that value is used to place newly activated entities on the left | ||
62 | side of the tree as much as possible. | ||
63 | |||
64 | The total number of running tasks in the runqueue is accounted through the | ||
65 | rq->cfs.load value, which is the sum of the weights of the tasks queued on the | ||
66 | runqueue. | ||
67 | |||
68 | CFS maintains a time-ordered rbtree, where all runnable tasks are sorted by the | ||
69 | p->se.vruntime key (there is a subtraction using rq->cfs.min_vruntime to | ||
70 | account for possible wraparounds). CFS picks the "leftmost" task from this | ||
71 | tree and sticks to it. | ||
72 | As the system progresses forwards, the executed tasks are put into the tree | ||
73 | more and more to the right --- slowly but surely giving a chance for every task | ||
74 | to become the "leftmost task" and thus get on the CPU within a deterministic | ||
75 | amount of time. | ||
76 | |||
77 | Summing up, CFS works like this: it runs a task a bit, and when the task | ||
78 | schedules (or a scheduler tick happens) the task's CPU usage is "accounted | ||
79 | for": the (small) time it just spent using the physical CPU is added to | ||
80 | p->se.vruntime. Once p->se.vruntime gets high enough so that another task | ||
81 | becomes the "leftmost task" of the time-ordered rbtree it maintains (plus a | ||
82 | small amount of "granularity" distance relative to the leftmost task so that we | ||
83 | do not over-schedule tasks and trash the cache), then the new leftmost task is | ||
84 | picked and the current task is preempted. | ||
85 | |||
86 | |||
87 | |||
88 | 4. SOME FEATURES OF CFS | ||
89 | |||
90 | CFS uses nanosecond granularity accounting and does not rely on any jiffies or | ||
91 | other HZ detail. Thus the CFS scheduler has no notion of "timeslices" in the | ||
92 | way the previous scheduler had, and has no heuristics whatsoever. There is | ||
93 | only one central tunable (you have to switch on CONFIG_SCHED_DEBUG): | ||
94 | |||
95 | /proc/sys/kernel/sched_granularity_ns | ||
96 | |||
97 | which 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 | ||
99 | for desktop workloads. SCHED_BATCH is handled by the CFS scheduler module too. | ||
100 | |||
101 | Due to its design, the CFS scheduler is not prone to any of the "attacks" that | ||
102 | exist today against the heuristics of the stock scheduler: fiftyp.c, thud.c, | ||
103 | chew.c, ring-test.c, massive_intr.c all work fine and do not impact | ||
104 | interactivity and produce the expected behavior. | ||
105 | |||
106 | The CFS scheduler has a much stronger handling of nice levels and SCHED_BATCH | ||
107 | than the previous vanilla scheduler: both types of workloads are isolated much | ||
108 | more aggressively. | ||
109 | |||
110 | SMP load-balancing has been reworked/sanitized: the runqueue-walking | ||
111 | assumptions are gone from the load-balancing code now, and iterators of the | ||
112 | scheduling modules are used. The balancing code got quite a bit simpler as a | ||
113 | result. | ||
114 | |||
115 | |||
116 | |||
117 | 5. Scheduling policies | ||
118 | |||
119 | CFS 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 | |||
133 | SCHED_FIFO/_RR are implemented in sched_rt.c and are as specified by | ||
134 | POSIX. | ||
135 | |||
136 | The command chrt from util-linux-ng 2.13.1.1 can set all of these except | ||
137 | SCHED_IDLE. | ||
144 | 138 | ||
145 | Group scheduler tunables: | ||
146 | 139 | ||
147 | When CONFIG_FAIR_USER_SCHED is defined, a directory is created in sysfs for | 140 | |
148 | each new user and a "cpu_share" file is added in that directory. | 141 | 6. SCHEDULING CLASSES |
142 | |||
143 | The new CFS scheduler has been designed in such a way to introduce "Scheduling | ||
144 | Classes," an extensible hierarchy of scheduler modules. These modules | ||
145 | encapsulate scheduling policy details and are handled by the scheduler core | ||
146 | without the core code assuming too much about them. | ||
147 | |||
148 | sched_fair.c implements the CFS scheduler described above. | ||
149 | |||
150 | sched_rt.c implements SCHED_FIFO and SCHED_RR semantics, in a simpler way than | ||
151 | the previous vanilla scheduler did. It uses 100 runqueues (for all 100 RT | ||
152 | priority levels, instead of 140 in the previous scheduler) and it needs no | ||
153 | expired array. | ||
154 | |||
155 | Scheduling classes are implemented through the sched_class structure, which | ||
156 | contains hooks to functions that must be called whenever an interesting event | ||
157 | occurs. | ||
158 | |||
159 | This 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 | |||
206 | 7. GROUP SCHEDULER EXTENSIONS TO CFS | ||
207 | |||
208 | Normally, the scheduler operates on individual tasks and strives to provide | ||
209 | fair CPU time to each task. Sometimes, it may be desirable to group tasks and | ||
210 | provide fair CPU time to each such task group. For example, it may be | ||
211 | desirable to first provide fair CPU time to each user on the system and then to | ||
212 | each task belonging to a user. | ||
213 | |||
214 | CONFIG_GROUP_SCHED strives to achieve exactly that. It lets tasks to be | ||
215 | grouped and divides CPU time fairly among such groups. | ||
216 | |||
217 | CONFIG_RT_GROUP_SCHED permits to group real-time (i.e., SCHED_FIFO and | ||
218 | SCHED_RR) tasks. | ||
219 | |||
220 | CONFIG_FAIR_GROUP_SCHED permits to group CFS (i.e., SCHED_NORMAL and | ||
221 | SCHED_BATCH) tasks. | ||
222 | |||
223 | At present, there are two (mutually exclusive) mechanisms to group tasks for | ||
224 | CPU 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 | |||
236 | Only one of these options to group tasks can be chosen and not both. | ||
237 | |||
238 | When CONFIG_USER_SCHED is defined, a directory is created in sysfs for each new | ||
239 | user 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 | ||
158 | CPU bandwidth between two users are divided in the ratio of their CPU shares. | 249 | CPU bandwidth between two users is divided in the ratio of their CPU shares. |
159 | For ex: if you would like user "root" to get twice the bandwidth of user | 250 | For 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 |
161 | cpu_share is twice "guest"'s cpu_share | 252 | is twice "guest"'s cpu_share. |
162 | |||
163 | 253 | ||
164 | When CONFIG_FAIR_CGROUP_SCHED is defined, a "cpu.shares" file is created | 254 | When CONFIG_CGROUP_SCHED is defined, a "cpu.shares" file is created for each |
165 | for each group created using the pseudo filesystem. See example steps | 255 | group created using the pseudo filesystem. See example steps below to create |
166 | below to create task groups and modify their CPU share using the "cgroups" | 256 | task groups and modify their CPU share using the "cgroups" pseudo filesystem. |
167 | pseudo 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 | |||
471 | vii. Move the function declarations for the management module from | 471 | vii. 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 | ||
477 | viii. Change default values for MEGARAID_NEWGEN, MEGARAID_MM, and | 477 | viii. 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 | ||
483 | ix. replace udelay with msleep | 483 | ix. 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 | ||
439 | Transport supplied functions | ||
440 | ---------------------------- | ||
441 | |||
442 | The 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 | |||
447 | Details: | ||
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 | */ | ||
458 | struct fc_vport * | ||
459 | fc_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 | */ | ||
471 | int | ||
472 | fc_vport_terminate(struct fc_vport *vport) | ||
473 | |||
474 | |||
439 | Credits | 475 | Credits |
440 | ======= | 476 | ======= |
441 | The following people have contributed to this document: | 477 | The 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 | ||
136 | static int spitz_mic_bias(struct snd_soc_dapm_widget* w, int event) | 136 | static 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 */ |
270 | static int corgi_amp_event(struct snd_soc_dapm_widget *w, int event) | 266 | static 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 | ||
7 | revamped completely for 2.4.x for several reasons. Foremost were | ||
8 | performance and complexity concerns. This document details these | ||
9 | new 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 | ||
12 | to functions and structures described here. | ||
13 | |||
14 | Probing and Detection | ||
15 | |||
16 | Each SBUS device inside the machine is described by a | ||
17 | structure called "struct sbus_dev". Likewise, each SBUS bus | ||
18 | found in the system is described by a "struct sbus_bus". For | ||
19 | each SBUS bus, the devices underneath are hung in a tree-like | ||
20 | fashion off of the bus structure. | ||
21 | |||
22 | The SBUS device structure contains enough information | ||
23 | for you to implement your device probing algorithm and obtain | ||
24 | the bits necessary to run your device. The most commonly | ||
25 | used members of this structure, and their typical usage, | ||
26 | will be detailed below. | ||
27 | |||
28 | Here is a piece of skeleton code for performing a device | ||
29 | probe 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 | ||
92 | describes what SBUS devices your driver is meant for. In the | ||
93 | simplest case you specify a string for the 'name' field. Every | ||
94 | SBUS device with a 'name' property matching your string will | ||
95 | be passed one-by-one to your .probe method. | ||
96 | |||
97 | You should store away your device private state structure | ||
98 | pointer in the drvdata area so that you can retrieve it later on | ||
99 | in your .remove method. | ||
100 | |||
101 | Any memory allocated, registers mapped, IRQs registered, | ||
102 | etc. must be undone by your .remove method so that all resources | ||
103 | of your device are released by the time it returns. | ||
104 | |||
105 | You should _NOT_ use the for_each_sbus(), for_each_sbusdev(), | ||
106 | and for_all_sbusdev() interfaces. They are deprecated, will be | ||
107 | removed, 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 | ||
112 | which describe each register set. We abuse struct resource for that. | ||
113 | They each correspond to the "reg" properties provided by the OBP firmware. | ||
114 | |||
115 | Before you can access your device's registers you must map | ||
116 | them. And later if you wish to shutdown your driver (for module | ||
117 | unload or similar) you must unmap them. You must treat them as | ||
118 | a 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 | ||
122 | typed as an "unsigned long". This is the type of the return value | ||
123 | of the mapping interface, and the arguments to the unmapping | ||
124 | interface. Let's say you want to map the first set of registers. | ||
125 | Perhaps 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 | ||
135 | interface 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 | ||
150 | cranky devices with broken OBP PROM. The sbus_ioremap uses only | ||
151 | a start address and flags from the resource structure. | ||
152 | Therefore it is possible to use the same resource to map | ||
153 | several sets of registers or even to fabricate a resource | ||
154 | structure if driver gets physical address from some private place. | ||
155 | This practice is discouraged though. Use whatever OBP PROM | ||
156 | provided to you. | ||
157 | |||
158 | And here is how you might unmap these registers later at | ||
159 | driver shutdown or module unload time, using the sbus_iounmap | ||
160 | interface: | ||
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 | ||
168 | interface routines at your disposal. Accesses are byte (8 bit), | ||
169 | word (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 | ||
179 | at 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 | ||
191 | 16 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 | ||
201 | noticed that these interfaces mimick the PCI interfaces of the | ||
202 | Linux 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 | ||
221 | to PCI but dissimilar to ISA, e.g. DMA masters supply address. | ||
222 | In contrast to PCI, however, that address (a bus address) is | ||
223 | translated by IOMMU before a memory access is performed and therefore | ||
224 | it is virtual. Sun calls this procedure DVMA. | ||
225 | |||
226 | Linux supports two styles of using SBUS DVMA: "consistent memory" | ||
227 | and "streaming DVMA". CPU view of consistent memory chunk is, well, | ||
228 | consistent with a view of a device. Think of it as an uncached memory. | ||
229 | Typically this way of doing DVMA is not very fast and drivers use it | ||
230 | mostly for control blocks or queues. On some CPUs we cannot flush or | ||
231 | invalidate individual pages or cache lines and doing explicit flushing | ||
232 | over ever little byte in every control block would be wasteful. | ||
233 | |||
234 | Streaming DVMA is a preferred way to transfer large amounts of data. | ||
235 | This process works in the following way: | ||
236 | 1. a CPU stops accessing a certain part of memory, | ||
237 | flushes its caches covering that memory; | ||
238 | 2. a device does DVMA accesses, then posts an interrupt; | ||
239 | 3. CPU invalidates its caches and starts to access the memory. | ||
240 | |||
241 | A single streaming DVMA operation can touch several discontiguous | ||
242 | regions of a virtual bus address space. This is called a scatter-gather | ||
243 | DVMA. | ||
244 | |||
245 | [TBD: Why do not we neither Solaris attempt to map disjoint pages | ||
246 | into a single virtual chunk with the help of IOMMU, so that non SG | ||
247 | DVMA masters would do SG? It'd be very helpful for RAID.] | ||
248 | |||
249 | In order to perform a consistent DVMA a driver does something | ||
250 | like 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 | ||
258 | is fed to the device so that it can do DVMA. This is typically | ||
259 | done 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 | ||
266 | memory suitable for it or pin down some user pages. Then it all works | ||
267 | like 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 | ||
284 | access data again and again without calling sbus_unmap_single. | ||
285 | However, CPU caches must be invalidated with sbus_dma_sync_single | ||
286 | before 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 | ||
291 | only with several memory segments at once for devices capable of | ||
292 | scatter-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 | ||
298 | discussed 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. | ||
308 | It is a nifty trick which we do not particularly recommend... | ||
309 | Just 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 | |||
96 | information via the structure "pxa2xx_spi_chip" found in | 96 | information 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 |
98 | will uses the configuration whenever the driver communicates with the slave | 98 | will uses the configuration whenever the driver communicates with the slave |
99 | device. | 99 | device. All fields are optional. |
100 | 100 | ||
101 | struct pxa2xx_spi_chip { | 101 | struct 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 | |||
112 | performance of pxa2xx_spi driver and misconfiguration will result in rx | 112 | performance of pxa2xx_spi driver and misconfiguration will result in rx |
113 | fifo overruns (especially in PIO mode transfers). Good default values are | 113 | fifo 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 | |||
118 | The range is 1 to 16 where zero indicates "use default". | ||
117 | 119 | ||
118 | The "pxa2xx_spi_chip.dma_burst_size" field is used to configure PXA2xx DMA | 120 | The "pxa2xx_spi_chip.dma_burst_size" field is used to configure PXA2xx DMA |
119 | engine and is related the "spi_device.bits_per_word" field. Read and understand | 121 | engine and is related the "spi_device.bits_per_word" field. Read and understand |
120 | the PXA2xx "Developer Manual" sections on the DMA controller and SSP Controllers | 122 | the PXA2xx "Developer Manual" sections on the DMA controller and SSP Controllers |
121 | to determine the correct value. An SSP configured for byte-wide transfers would | 123 | to determine the correct value. An SSP configured for byte-wide transfers would |
122 | use a value of 8. | 124 | use a value of 8. The driver will determine a reasonable default if |
125 | dma_burst_size == 0. | ||
123 | 126 | ||
124 | The "pxa2xx_spi_chip.timeout" fields is used to efficiently handle | 127 | The "pxa2xx_spi_chip.timeout" fields is used to efficiently handle |
125 | trailing bytes in the SSP receiver fifo. The correct value for this field is | 128 | trailing 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 | |||
137 | NULL, the pxa2xx_spi master controller driver assumes that the SSP port is | 140 | NULL, the pxa2xx_spi master controller driver assumes that the SSP port is |
138 | configured to use SSPFRM instead. | 141 | configured to use SSPFRM instead. |
139 | 142 | ||
140 | NSSP SALVE SAMPLE | 143 | NOTE: the SPI driver cannot control the chip select if SSPFRM is used, so the |
144 | chipselect is dropped after each spi_transfer. Most devices need chip select | ||
145 | asserted around the complete message. Use SSPFRM as a GPIO (through cs_control) | ||
146 | to accomodate these chips. | ||
147 | |||
148 | |||
149 | NSSP SLAVE SAMPLE | ||
141 | ----------------- | 150 | ----------------- |
142 | The pxa2xx_spi_chip structure is passed to the pxa2xx_spi driver in the | 151 | The 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 | ||
207 | DMA and PIO I/O Support | 216 | DMA and PIO I/O Support |
208 | ----------------------- | 217 | ----------------------- |
209 | The pxa2xx_spi driver support both DMA and interrupt driven PIO message | 218 | The pxa2xx_spi driver supports both DMA and interrupt driven PIO message |
210 | transfers. The driver defaults to PIO mode and DMA transfers must enabled by | 219 | transfers. The driver defaults to PIO mode and DMA transfers must be enabled |
211 | setting the "enable_dma" flag in the "pxa2xx_spi_master" structure and | 220 | by setting the "enable_dma" flag in the "pxa2xx_spi_master" structure. The DMA |
212 | ensuring that the "pxa2xx_spi_chip.dma_burst_size" field is non-zero. The DMA | 221 | mode supports both coherent and stream based DMA mappings. |
213 | mode support both coherent and stream based DMA mappings. | ||
214 | 222 | ||
215 | The following logic is used to determine the type of I/O to be used on | 223 | The following logic is used to determine the type of I/O to be used on |
216 | a per "spi_transfer" basis: | 224 | a per "spi_transfer" basis: |
217 | 225 | ||
218 | if !enable_dma or dma_burst_size == 0 then | 226 | if !enable_dma then |
219 | always use PIO transfers | 227 | always use PIO transfers |
220 | 228 | ||
229 | if spi_message.len > 8191 then | ||
230 | print "rate limited" warning | ||
231 | use PIO transfers | ||
232 | |||
221 | if spi_message.is_dma_mapped and rx_dma_buf != 0 and tx_dma_buf != 0 then | 233 | if 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 @@ | |||
1 | 00-INDEX | ||
2 | - this file | ||
3 | highres.txt | ||
4 | - High resolution timers and dynamic ticks design notes | ||
5 | hpet.txt | ||
6 | - High Precision Event Timer Driver for Linux | ||
7 | hrtimers.txt | ||
8 | - subsystem for high-resolution kernel timers | ||
9 | timer_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 | ||
3 | The High Precision Event Timer (HPET) hardware is the future replacement | 3 | The High Precision Event Timer (HPET) hardware follows a specification |
4 | for the 8254 and Real Time Clock (RTC) periodic timer functionality. | 4 | by Intel and Microsoft which can be found at |
5 | Each HPET can have up to 32 timers. It is possible to configure the | 5 | |
6 | first two timers as legacy replacements for 8254 and RTC periodic timers. | 6 | http://www.intel.com/technology/architecture/hpetspec.htm |
7 | A specification done by Intel and Microsoft can be found at | 7 | |
8 | <http://www.intel.com/technology/architecture/hpetspec.htm>. | 8 | Each HPET has one fixed-rate counter (at 10+ MHz, hence "High Precision") |
9 | and up to 32 comparators. Normally three or more comparators are provided, | ||
10 | each of which can generate oneshot interupts and at least one of which has | ||
11 | additional hardware to support periodic interrupts. The comparators are | ||
12 | also called "timers", which can be misleading since usually timers are | ||
13 | independent of each other ... these share a counter, complicating resets. | ||
14 | |||
15 | HPET devices can support two interrupt routing modes. In one mode, the | ||
16 | comparators are additional interrupt sources with no particular system | ||
17 | role. Many x86 BIOS writers don't route HPET interrupts at all, which | ||
18 | prevents use of that mode. They support the other "legacy replacement" | ||
19 | mode where the first two comparators block interrupts from 8254 timers | ||
20 | and from the RTC. | ||
9 | 21 | ||
10 | The driver supports detection of HPET driver allocation and initialization | 22 | The driver supports detection of HPET driver allocation and initialization |
11 | of the HPET before the driver module_init routine is called. This enables | 23 | of the HPET before the driver module_init routine is called. This enables |
12 | platform code which uses timer 0 or 1 as the main timer to intercept HPET | 24 | platform code which uses timer 0 or 1 as the main timer to intercept HPET |
13 | initialization. An example of this initialization can be found in | 25 | initialization. An example of this initialization can be found in |
14 | arch/i386/kernel/time_hpet.c. | 26 | arch/x86/kernel/hpet.c. |
15 | 27 | ||
16 | The driver provides two APIs which are very similar to the API found in | 28 | The driver provides a userspace API which resembles the API found in the |
17 | the rtc.c driver. There is a user space API and a kernel space API. | 29 | RTC driver framework. An example user space program is provided below. |
18 | An 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 | |||
290 | The 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 | |||
296 | The kernel module using this interface fills in the ht_func and ht_data | ||
297 | members of the hpet_task structure before calling hpet_register. | ||
298 | hpet_control simply vectors to the hpet_ioctl routine and has the same | ||
299 | commands and respective arguments as the user API. hpet_unregister | ||
300 | is 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 | |||
52 | the call returns. They may be unlinked later but will be unlinked in | 52 | the call returns. They may be unlinked later but will be unlinked in |
53 | finite time. | 53 | finite time. |
54 | 54 | ||
55 | usb_scuttle_anchored_urbs() | ||
56 | --------------------------- | ||
57 | |||
58 | All URBs of an anchor are unanchored en masse. | ||
59 | |||
55 | usb_wait_anchor_empty_timeout() | 60 | usb_wait_anchor_empty_timeout() |
56 | ------------------------------- | 61 | ------------------------------- |
57 | 62 | ||
@@ -59,4 +64,16 @@ This function waits for all URBs associated with an anchor to finish | |||
59 | or a timeout, whichever comes first. Its return value will tell you | 64 | or a timeout, whichever comes first. Its return value will tell you |
60 | whether the timeout was reached. | 65 | whether the timeout was reached. |
61 | 66 | ||
67 | usb_anchor_empty() | ||
68 | ------------------ | ||
69 | |||
70 | Returns true if no URBs are associated with an anchor. Locking | ||
71 | is the caller's responsibility. | ||
72 | |||
73 | usb_get_from_anchor() | ||
74 | --------------------- | ||
62 | 75 | ||
76 | Returns the oldest anchored URB of an anchor. The URB is unanchored | ||
77 | and returned with a reference. As you may mix URBs to several | ||
78 | destinations in one anchor you have no guarantee the chronologically | ||
79 | first 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 @@ | |||
1 | USB 7-Segment Numeric Display | ||
2 | Manufactured by Delcom Engineering | ||
3 | |||
4 | Device Information | ||
5 | ------------------ | ||
6 | USB VENDOR_ID 0x0fc5 | ||
7 | USB PRODUCT_ID 0x1227 | ||
8 | Both the 6 character and 8 character displays have PRODUCT_ID, | ||
9 | and according to Delcom Engineering no queryable information | ||
10 | can be obtained from the device to tell them apart. | ||
11 | |||
12 | Device Modes | ||
13 | ------------ | ||
14 | By default, the driver assumes the display is only 6 characters | ||
15 | The mode for 6 characters is: | ||
16 | MSB 0x06; LSB 0x3f | ||
17 | For the 8 character display: | ||
18 | MSB 0x08; LSB 0xff | ||
19 | The device can accept "text" either in raw, hex, or ascii textmode. | ||
20 | raw controls each segment manually, | ||
21 | hex expects a value between 0-15 per character, | ||
22 | ascii expects a value between '0'-'9' and 'A'-'F'. | ||
23 | The default is ascii. | ||
24 | |||
25 | Device Operation | ||
26 | ---------------- | ||
27 | 1. Turn on the device: | ||
28 | echo 1 > /sys/bus/usb/.../powered | ||
29 | 2. Set the device's mode: | ||
30 | echo $mode_msb > /sys/bus/usb/.../mode_msb | ||
31 | echo $mode_lsb > /sys/bus/usb/.../mode_lsb | ||
32 | 3. Set the textmode: | ||
33 | echo $textmode > /sys/bus/usb/.../textmode | ||
34 | 4. 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) | ||
38 | 5. 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 | ||
351 | There also are a couple of utility routines drivers can use: | 351 | There 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 | |||
359 | The conventional usage pattern is that a driver calls | 359 | The conventional usage pattern is that a driver calls |
360 | usb_autopm_get_interface() in its open routine and | 360 | usb_autopm_get_interface() in its open routine and |
361 | usb_autopm_put_interface() in its close or release routine. But | 361 | usb_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 @@ | |||
150 | 149 -> Typhoon TV-Tuner PCI (50684) | 150 | 149 -> Typhoon TV-Tuner PCI (50684) |
151 | 150 -> Geovision GV-600 [008a:763c] | 151 | 150 -> Geovision GV-600 [008a:763c] |
152 | 151 -> Kozumi KTV-01C | 152 | 151 -> Kozumi KTV-01C |
153 | 152 -> 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 @@ | |||
145 | 144 -> Beholder BeholdTV M6 Extra [5ace:6193] | 145 | 144 -> Beholder BeholdTV M6 Extra [5ace:6193] |
146 | 145 -> AVerMedia MiniPCI DVB-T Hybrid M103 [1461:f636] | 146 | 145 -> AVerMedia MiniPCI DVB-T Hybrid M103 [1461:f636] |
147 | 146 -> ASUSTeK P7131 Analog | 147 | 146 -> ASUSTeK P7131 Analog |
148 | 147 -> Asus Tiger 3in1 [1043:4878] | ||
149 | 148 -> Encore ENLTV-FM v5.3 [1a7f:2008] | ||
150 | 149 -> Avermedia PCI pure analog (M135A) [1461:f11d] | ||
151 | 150 -> Zogis Real Angel 220 | ||
152 | 151 -> ADS Tech Instant HDTV [1421:0380] | ||
153 | 152 -> 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 | |||
74 | tuner=73 - Samsung TCPG 6121P30A | 74 | tuner=73 - Samsung TCPG 6121P30A |
75 | tuner=75 - Philips TEA5761 FM Radio | 75 | tuner=75 - Philips TEA5761 FM Radio |
76 | tuner=76 - Xceive 5000 tuner | 76 | tuner=76 - Xceive 5000 tuner |
77 | tuner=77 - TCL tuner MF02GIP-5N-E | ||
78 | tuner=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: | |||
7 | xxxx vend:prod | 7 | xxxx vend:prod |
8 | ---- | 8 | ---- |
9 | spca501 0000:0000 MystFromOri Unknow Camera | 9 | spca501 0000:0000 MystFromOri Unknow Camera |
10 | m5602 0402:5602 ALi Video Camera Controller | ||
10 | spca501 040a:0002 Kodak DVC-325 | 11 | spca501 040a:0002 Kodak DVC-325 |
11 | spca500 040a:0300 Kodak EZ200 | 12 | spca500 040a:0300 Kodak EZ200 |
12 | zc3xx 041e:041e Creative WebCam Live! | 13 | zc3xx 041e:041e Creative WebCam Live! |
@@ -42,6 +43,7 @@ zc3xx 0458:7007 Genius VideoCam V2 | |||
42 | zc3xx 0458:700c Genius VideoCam V3 | 43 | zc3xx 0458:700c Genius VideoCam V3 |
43 | zc3xx 0458:700f Genius VideoCam Web V2 | 44 | zc3xx 0458:700f Genius VideoCam Web V2 |
44 | sonixj 0458:7025 Genius Eye 311Q | 45 | sonixj 0458:7025 Genius Eye 311Q |
46 | sonixj 0458:702e Genius Slim 310 NB | ||
45 | sonixj 045e:00f5 MicroSoft VX3000 | 47 | sonixj 045e:00f5 MicroSoft VX3000 |
46 | sonixj 045e:00f7 MicroSoft VX1000 | 48 | sonixj 045e:00f7 MicroSoft VX1000 |
47 | ov519 045e:028c Micro$oft xbox cam | 49 | ov519 045e:028c Micro$oft xbox cam |
@@ -81,7 +83,7 @@ spca561 046d:092b Labtec Webcam Plus | |||
81 | spca561 046d:092c Logitech QC chat Elch2 | 83 | spca561 046d:092c Logitech QC chat Elch2 |
82 | spca561 046d:092d Logitech QC Elch2 | 84 | spca561 046d:092d Logitech QC Elch2 |
83 | spca561 046d:092e Logitech QC Elch2 | 85 | spca561 046d:092e Logitech QC Elch2 |
84 | spca561 046d:092f Logitech QC Elch2 | 86 | spca561 046d:092f Logitech QuickCam Express Plus |
85 | sunplus 046d:0960 Logitech ClickSmart 420 | 87 | sunplus 046d:0960 Logitech ClickSmart 420 |
86 | sunplus 0471:0322 Philips DMVC1300K | 88 | sunplus 0471:0322 Philips DMVC1300K |
87 | zc3xx 0471:0325 Philips SPC 200 NC | 89 | zc3xx 0471:0325 Philips SPC 200 NC |
@@ -96,6 +98,29 @@ sunplus 04a5:3003 Benq DC 1300 | |||
96 | sunplus 04a5:3008 Benq DC 1500 | 98 | sunplus 04a5:3008 Benq DC 1500 |
97 | sunplus 04a5:300a Benq DC 3410 | 99 | sunplus 04a5:300a Benq DC 3410 |
98 | spca500 04a5:300c Benq DC 1016 | 100 | spca500 04a5:300c Benq DC 1016 |
101 | finepix 04cb:0104 Fujifilm FinePix 4800 | ||
102 | finepix 04cb:0109 Fujifilm FinePix A202 | ||
103 | finepix 04cb:010b Fujifilm FinePix A203 | ||
104 | finepix 04cb:010f Fujifilm FinePix A204 | ||
105 | finepix 04cb:0111 Fujifilm FinePix A205 | ||
106 | finepix 04cb:0113 Fujifilm FinePix A210 | ||
107 | finepix 04cb:0115 Fujifilm FinePix A303 | ||
108 | finepix 04cb:0117 Fujifilm FinePix A310 | ||
109 | finepix 04cb:0119 Fujifilm FinePix F401 | ||
110 | finepix 04cb:011b Fujifilm FinePix F402 | ||
111 | finepix 04cb:011d Fujifilm FinePix F410 | ||
112 | finepix 04cb:0121 Fujifilm FinePix F601 | ||
113 | finepix 04cb:0123 Fujifilm FinePix F700 | ||
114 | finepix 04cb:0125 Fujifilm FinePix M603 | ||
115 | finepix 04cb:0127 Fujifilm FinePix S300 | ||
116 | finepix 04cb:0129 Fujifilm FinePix S304 | ||
117 | finepix 04cb:012b Fujifilm FinePix S500 | ||
118 | finepix 04cb:012d Fujifilm FinePix S602 | ||
119 | finepix 04cb:012f Fujifilm FinePix S700 | ||
120 | finepix 04cb:0131 Fujifilm FinePix unknown model | ||
121 | finepix 04cb:013b Fujifilm FinePix unknown model | ||
122 | finepix 04cb:013d Fujifilm FinePix unknown model | ||
123 | finepix 04cb:013f Fujifilm FinePix F420 | ||
99 | sunplus 04f1:1001 JVC GC A50 | 124 | sunplus 04f1:1001 JVC GC A50 |
100 | spca561 04fc:0561 Flexcam 100 | 125 | spca561 04fc:0561 Flexcam 100 |
101 | sunplus 04fc:500c Sunplus CA500C | 126 | sunplus 04fc:500c Sunplus CA500C |
@@ -181,6 +206,7 @@ pac207 093a:2468 PAC207 | |||
181 | pac207 093a:2470 Genius GF112 | 206 | pac207 093a:2470 Genius GF112 |
182 | pac207 093a:2471 Genius VideoCam ge111 | 207 | pac207 093a:2471 Genius VideoCam ge111 |
183 | pac207 093a:2472 Genius VideoCam ge110 | 208 | pac207 093a:2472 Genius VideoCam ge110 |
209 | pac207 093a:2476 Genius e-Messenger 112 | ||
184 | pac7311 093a:2600 PAC7311 Typhoon | 210 | pac7311 093a:2600 PAC7311 Typhoon |
185 | pac7311 093a:2601 Philips SPC 610 NC | 211 | pac7311 093a:2601 Philips SPC 610 NC |
186 | pac7311 093a:2603 PAC7312 | 212 | pac7311 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 @@ | |||
1 | This document describes the ALi m5602 bridge connected | ||
2 | to the following supported sensors: | ||
3 | OmniVision OV9650, | ||
4 | Samsung s5k83a, | ||
5 | Samsung s5k4aa, | ||
6 | Micron mt9m111, | ||
7 | Pixel plus PO1030 | ||
8 | |||
9 | This driver mimics the windows drivers, which have a braindead implementation sending bayer-encoded frames at VGA resolution. | ||
10 | In 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 | |||
12 | Anyway, 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 | |||
4 | Terminology | ||
5 | ----------- | ||
6 | |||
7 | The 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 | |||
18 | Purpose of the soc-camera subsystem | ||
19 | ----------------------------------- | ||
20 | |||
21 | The soc-camera subsystem provides a unified API between camera host drivers and | ||
22 | camera sensor drivers. It implements a V4L2 interface to the user, currently | ||
23 | only the mmap method is supported. | ||
24 | |||
25 | This subsystem has been written to connect drivers for System-on-Chip (SoC) | ||
26 | video capture interfaces with drivers for CMOS camera sensor chips to enable | ||
27 | the reuse of sensor drivers with various hosts. The subsystem has been designed | ||
28 | to support multiple camera host interfaces and multiple cameras per interface, | ||
29 | although most applications have only one camera sensor. | ||
30 | |||
31 | Existing drivers | ||
32 | ---------------- | ||
33 | |||
34 | As of 2.6.27-rc4 there are two host drivers in the mainline: pxa_camera.c for | ||
35 | PXA27x SoCs and sh_mobile_ceu_camera.c for SuperH SoCs, and four sensor drivers: | ||
36 | mt9m001.c, mt9m111.c, mt9v022.c and a generic soc_camera_platform.c driver. This | ||
37 | list is not supposed to be updated, look for more examples in your tree. | ||
38 | |||
39 | Camera host API | ||
40 | --------------- | ||
41 | |||
42 | A host camera driver is registered using the | ||
43 | |||
44 | soc_camera_host_register(struct soc_camera_host *); | ||
45 | |||
46 | function. The host object can be initialized as follows: | ||
47 | |||
48 | static struct soc_camera_host pxa_soc_camera_host = { | ||
49 | .drv_name = PXA_CAM_DRV_NAME, | ||
50 | .ops = &pxa_soc_camera_host_ops, | ||
51 | }; | ||
52 | |||
53 | All camera host methods are passed in a struct soc_camera_host_ops: | ||
54 | |||
55 | static 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 | ||
72 | from the host, apart from performing host-internal tasks they shall also call | ||
73 | sensor driver's .init and .release methods respectively. .suspend and .resume | ||
74 | methods implement host's power-management functionality and its their | ||
75 | responsibility to call respective sensor's methods. .try_bus_param and | ||
76 | .set_bus_param are used to negotiate physical connection parameters between the | ||
77 | host and the sensor. .init_videobuf is called by soc-camera core when a | ||
78 | video-device is opened, further video-buffer management is implemented completely | ||
79 | by the specific camera host driver. The rest of the methods are called from | ||
80 | respective V4L2 operations. | ||
81 | |||
82 | Camera API | ||
83 | ---------- | ||
84 | |||
85 | Sensor drivers can use struct soc_camera_link, typically provided by the | ||
86 | platform, and used to specify to which camera host bus the sensor is connected, | ||
87 | and arbitrarily provide platform .power and .reset methods for the camera. | ||
88 | soc_camera_device_register() and soc_camera_device_unregister() functions are | ||
89 | used to add a sensor driver to or remove one from the system. The registration | ||
90 | function takes a pointer to struct soc_camera_device as the only parameter. | ||
91 | This 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 | |||
110 | struct soc_camera_ops provides .probe and .remove methods, which are called by | ||
111 | the soc-camera core, when a camera is matched against or removed from a camera | ||
112 | host bus, .init, .release, .suspend, and .resume are called from the camera host | ||
113 | driver as discussed above. Other members of this struct provide respective V4L2 | ||
114 | functionality. | ||
115 | |||
116 | struct soc_camera_device also links to an array of struct soc_camera_data_format, | ||
117 | listing pixel formats, supported by the camera. | ||
118 | |||
119 | -- | ||
120 | Author: 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 @@ | |||
1 | 00-INDEX | 1 | 00-INDEX |
2 | - This file | 2 | - This file |
3 | slaves/ | ||
4 | - Drivers that provide support for specific family codes. | ||
3 | masters/ | 5 | masters/ |
4 | - Individual chips providing 1-wire busses. | 6 | - Individual chips providing 1-wire busses. |
5 | w1.generic | 7 | w1.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. | |||
16 | DS9490(R) is a USB <-> W1 bus master device | 16 | DS9490(R) is a USB <-> W1 bus master device |
17 | which has 0x81 family ID integrated chip and DS2490 | 17 | which has 0x81 family ID integrated chip and DS2490 |
18 | low-level operational chip. | 18 | low-level operational chip. |
19 | |||
20 | Notes 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 @@ | |||
1 | 00-INDEX | ||
2 | - This file | ||
3 | w1_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 @@ | |||
1 | Kernel driver w1_therm | ||
2 | ==================== | ||
3 | |||
4 | Supported chips: | ||
5 | * Maxim ds18*20 based temperature sensors. | ||
6 | |||
7 | Author: Evgeniy Polyakov <johnpol@2ka.mipt.ru> | ||
8 | |||
9 | |||
10 | Description | ||
11 | ----------- | ||
12 | |||
13 | w1_therm provides basic temperature conversion for ds18*20 devices. | ||
14 | supported family codes: | ||
15 | W1_THERM_DS18S20 0x10 | ||
16 | W1_THERM_DS1822 0x22 | ||
17 | W1_THERM_DS18B20 0x28 | ||
18 | |||
19 | Support is provided through the sysfs w1_slave file. Each open and | ||
20 | read sequence will initiate a temperature conversion then provide two | ||
21 | lines of ASCII output. The first line contains the nine hex bytes | ||
22 | read along with a calculated crc value and YES or NO if it matched. | ||
23 | If the crc matched the returned values are retained. The second line | ||
24 | displays the retained values along with a temperature in millidegrees | ||
25 | Centigrade after t=. | ||
26 | |||
27 | Parasite powered devices are limited to one slave performing a | ||
28 | temperature conversion at a time. If none of the devices are parasite | ||
29 | powered it would be possible to convert all the devices at the same | ||
30 | time and then go back to read individual sensors. That isn't | ||
31 | currently supported. The driver also doesn't support reduced | ||
32 | precision (which would also reduce the conversion time). | ||
33 | |||
34 | The module parameter strong_pullup can be set to 0 to disable the | ||
35 | strong pullup or 1 to enable. If enabled the 5V strong pullup will be | ||
36 | enabled when the conversion is taking place provided the master driver | ||
37 | must support the strong pullup (or it falls back to a pullup | ||
38 | resistor). The DS18b20 temperature sensor specification lists a | ||
39 | maximum current draw of 1.5mA and that a 5k pullup resistor is not | ||
40 | sufficient. The strong pullup is designed to provide the additional | ||
41 | current 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 |
80 | bus - (standard) symlink to the w1 bus | 80 | bus - (standard) symlink to the w1 bus |
81 | driver - (standard) symlink to the w1 driver | 81 | driver - (standard) symlink to the w1 driver |
82 | w1_master_add - Manually register a slave device | ||
82 | w1_master_attempts - the number of times a search was attempted | 83 | w1_master_attempts - the number of times a search was attempted |
83 | w1_master_max_slave_count | 84 | w1_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 |
85 | w1_master_name - the name of the device (w1_bus_masterX) | 86 | w1_master_name - the name of the device (w1_bus_masterX) |
87 | w1_master_pullup - 5V strong pullup 0 enabled, 1 disabled | ||
88 | w1_master_remove - Manually remove a slave device | ||
86 | w1_master_search - the number of searches left to do, -1=continual (default) | 89 | w1_master_search - the number of searches left to do, -1=continual (default) |
87 | w1_master_slave_count | 90 | w1_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 | |||
90 | w1_master_timeout - the delay in seconds between searches | 93 | w1_master_timeout - the delay in seconds between searches |
91 | 94 | ||
92 | If you have a w1 bus that never changes (you don't add or remove devices), | 95 | If you have a w1 bus that never changes (you don't add or remove devices), |
93 | you can set w1_master_search to a positive value to disable searches. | 96 | you can set the module parameter search_count to a small positive number |
97 | for an initially small number of bus searches. Alternatively it could be | ||
98 | set to zero, then manually add the slave device serial numbers by | ||
99 | w1_master_add device file. The w1_master_add and w1_master_remove files | ||
100 | generally only make sense when searching is disabled, as a search will | ||
101 | redetect manually removed devices that are present and timeout manually | ||
102 | added devices that aren't on the bus. | ||
94 | 103 | ||
95 | 104 | ||
96 | w1 slave sysfs interface | 105 | w1 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 @@ | |||
1 | 00-INDEX | ||
2 | - this file | ||
3 | mtrr.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 | ||
309 | Field name: start_sys | 309 | Field name: start_sys |
310 | Type: read | 310 | Type: read |
311 | Offset/size: 0x20c/4 | 311 | Offset/size: 0x20c/2 |
312 | Protocol: 2.00+ | 312 | Protocol: 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 | |||
87 | reg01: base=0xfb000000 (4016MB), size= 16MB: write-combining, count=1 | 87 | reg01: base=0xfb000000 (4016MB), size= 16MB: write-combining, count=1 |
88 | reg02: base=0xfb000000 (4016MB), size= 4kB: uncachable, count=1 | 88 | reg02: base=0xfb000000 (4016MB), size= 4kB: uncachable, count=1 |
89 | 89 | ||
90 | Some cards (especially Voodoo Graphics boards) need this 4 kB area | 90 | Some cards (especially Voodoo Graphics boards) need this 4 kB area |
91 | excluded from the beginning of the region because it is used for | 91 | excluded from the beginning of the region because it is used for |
92 | registers. | 92 | registers. |
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 | |||
14 | ones that will be supported at this time are Write-back, Uncached, | 14 | ones that will be supported at this time are Write-back, Uncached, |
15 | Write-combined and Uncached Minus. | 15 | Write-combined and Uncached Minus. |
16 | 16 | ||
17 | |||
18 | PAT APIs | ||
19 | -------- | ||
20 | |||
17 | There are many different APIs in the kernel that allows setting of memory | 21 | There are many different APIs in the kernel that allows setting of memory |
18 | attributes at the page level. In order to avoid aliasing, these interfaces | 22 | attributes at the page level. In order to avoid aliasing, these interfaces |
19 | should be used thoughtfully. Below is a table of interfaces available, | 23 | should be used thoughtfully. Below is a table of interfaces available, |
@@ -26,38 +30,38 @@ address range to avoid any aliasing. | |||
26 | API | RAM | ACPI,... | Reserved/Holes | | 30 | API | RAM | ACPI,... | Reserved/Holes | |
27 | -----------------------|----------|------------|------------------| | 31 | -----------------------|----------|------------|------------------| |
28 | | | | | | 32 | | | | | |
29 | ioremap | -- | UC | UC | | 33 | ioremap | -- | UC- | UC- | |
30 | | | | | | 34 | | | | | |
31 | ioremap_cache | -- | WB | WB | | 35 | ioremap_cache | -- | WB | WB | |
32 | | | | | | 36 | | | | | |
33 | ioremap_nocache | -- | UC | UC | | 37 | ioremap_nocache | -- | UC- | UC- | |
34 | | | | | | 38 | | | | | |
35 | ioremap_wc | -- | -- | WC | | 39 | ioremap_wc | -- | -- | WC | |
36 | | | | | | 40 | | | | | |
37 | set_memory_uc | UC | -- | -- | | 41 | set_memory_uc | UC- | -- | -- | |
38 | set_memory_wb | | | | | 42 | set_memory_wb | | | | |
39 | | | | | | 43 | | | | | |
40 | set_memory_wc | WC | -- | -- | | 44 | set_memory_wc | WC | -- | -- | |
41 | set_memory_wb | | | | | 45 | set_memory_wb | | | | |
42 | | | | | | 46 | | | | | |
43 | pci sysfs resource | -- | -- | UC | | 47 | pci sysfs resource | -- | -- | UC- | |
44 | | | | | | 48 | | | | | |
45 | pci sysfs resource_wc | -- | -- | WC | | 49 | pci sysfs resource_wc | -- | -- | WC | |
46 | is IORESOURCE_PREFETCH| | | | | 50 | is IORESOURCE_PREFETCH| | | | |
47 | | | | | | 51 | | | | | |
48 | pci proc | -- | -- | UC | | 52 | pci proc | -- | -- | UC- | |
49 | !PCIIOC_WRITE_COMBINE | | | | | 53 | !PCIIOC_WRITE_COMBINE | | | | |
50 | | | | | | 54 | | | | | |
51 | pci proc | -- | -- | WC | | 55 | pci 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 | ||
99 | Drivers should use set_memory_[uc|wc] to set access type for RAM ranges. | 103 | Drivers should use set_memory_[uc|wc] to set access type for RAM ranges. |
100 | 104 | ||
105 | |||
106 | PAT debugging | ||
107 | ------------- | ||
108 | |||
109 | With 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 | ||
113 | PAT memtype list: | ||
114 | uncached-minus @ 0x7fadf000-0x7fae0000 | ||
115 | uncached-minus @ 0x7fb19000-0x7fb1a000 | ||
116 | uncached-minus @ 0x7fb1a000-0x7fb1b000 | ||
117 | uncached-minus @ 0x7fb1b000-0x7fb1c000 | ||
118 | uncached-minus @ 0x7fb1c000-0x7fb1d000 | ||
119 | uncached-minus @ 0x7fb1d000-0x7fb1e000 | ||
120 | uncached-minus @ 0x7fb1e000-0x7fb25000 | ||
121 | uncached-minus @ 0x7fb25000-0x7fb26000 | ||
122 | uncached-minus @ 0x7fb26000-0x7fb27000 | ||
123 | uncached-minus @ 0x7fb27000-0x7fb28000 | ||
124 | uncached-minus @ 0x7fb28000-0x7fb2e000 | ||
125 | uncached-minus @ 0x7fb2e000-0x7fb2f000 | ||
126 | uncached-minus @ 0x7fb2f000-0x7fb30000 | ||
127 | uncached-minus @ 0x7fb31000-0x7fb32000 | ||
128 | uncached-minus @ 0x80000000-0x90000000 | ||
129 | |||
130 | This list shows physical address ranges and various PAT settings used to | ||
131 | access those physical address ranges. | ||
132 | |||
133 | Another, more verbose way of getting PAT related debug messages is with | ||
134 | "debugpat" boot parameter. With this parameter, various debug messages are | ||
135 | printed 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 | |||
61 | Early Console | 57 | Early 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 | |||