diff options
Diffstat (limited to 'Documentation')
-rw-r--r-- | Documentation/DocBook/device-drivers.tmpl | 1 | ||||
-rw-r--r-- | Documentation/DocBook/kernel-api.tmpl | 1 | ||||
-rw-r--r-- | Documentation/DocBook/kernel-locking.tmpl | 6 | ||||
-rw-r--r-- | Documentation/block/cfq-iosched.txt | 45 | ||||
-rw-r--r-- | Documentation/cgroups/blkio-controller.txt | 28 | ||||
-rw-r--r-- | Documentation/gpio.txt | 22 | ||||
-rw-r--r-- | Documentation/hwmon/sysfs-interface | 7 | ||||
-rw-r--r-- | Documentation/kernel-doc-nano-HOWTO.txt | 5 | ||||
-rw-r--r-- | Documentation/mutex-design.txt | 3 | ||||
-rw-r--r-- | Documentation/networking/e1000.txt | 373 | ||||
-rw-r--r-- | Documentation/networking/e1000e.txt | 302 | ||||
-rw-r--r--[-rwxr-xr-x] | Documentation/networking/ixgbevf.txt | 40 | ||||
-rw-r--r-- | Documentation/power/regulator/overview.txt | 2 | ||||
-rw-r--r-- | Documentation/sound/alsa/HD-Audio-Models.txt | 1 | ||||
-rw-r--r-- | Documentation/workqueue.txt | 380 |
15 files changed, 886 insertions, 330 deletions
diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl index ecd35e9d441..feca0758391 100644 --- a/Documentation/DocBook/device-drivers.tmpl +++ b/Documentation/DocBook/device-drivers.tmpl | |||
@@ -46,7 +46,6 @@ | |||
46 | 46 | ||
47 | <sect1><title>Atomic and pointer manipulation</title> | 47 | <sect1><title>Atomic and pointer manipulation</title> |
48 | !Iarch/x86/include/asm/atomic.h | 48 | !Iarch/x86/include/asm/atomic.h |
49 | !Iarch/x86/include/asm/unaligned.h | ||
50 | </sect1> | 49 | </sect1> |
51 | 50 | ||
52 | <sect1><title>Delaying, scheduling, and timer routines</title> | 51 | <sect1><title>Delaying, scheduling, and timer routines</title> |
diff --git a/Documentation/DocBook/kernel-api.tmpl b/Documentation/DocBook/kernel-api.tmpl index a20c6f6fffc..6899f471fb1 100644 --- a/Documentation/DocBook/kernel-api.tmpl +++ b/Documentation/DocBook/kernel-api.tmpl | |||
@@ -57,7 +57,6 @@ | |||
57 | </para> | 57 | </para> |
58 | 58 | ||
59 | <sect1><title>String Conversions</title> | 59 | <sect1><title>String Conversions</title> |
60 | !Ilib/vsprintf.c | ||
61 | !Elib/vsprintf.c | 60 | !Elib/vsprintf.c |
62 | </sect1> | 61 | </sect1> |
63 | <sect1><title>String Manipulation</title> | 62 | <sect1><title>String Manipulation</title> |
diff --git a/Documentation/DocBook/kernel-locking.tmpl b/Documentation/DocBook/kernel-locking.tmpl index 0b1a3f97f28..a0d479d1e1d 100644 --- a/Documentation/DocBook/kernel-locking.tmpl +++ b/Documentation/DocBook/kernel-locking.tmpl | |||
@@ -1961,6 +1961,12 @@ machines due to caching. | |||
1961 | </sect1> | 1961 | </sect1> |
1962 | </chapter> | 1962 | </chapter> |
1963 | 1963 | ||
1964 | <chapter id="apiref"> | ||
1965 | <title>Mutex API reference</title> | ||
1966 | !Iinclude/linux/mutex.h | ||
1967 | !Ekernel/mutex.c | ||
1968 | </chapter> | ||
1969 | |||
1964 | <chapter id="references"> | 1970 | <chapter id="references"> |
1965 | <title>Further reading</title> | 1971 | <title>Further reading</title> |
1966 | 1972 | ||
diff --git a/Documentation/block/cfq-iosched.txt b/Documentation/block/cfq-iosched.txt new file mode 100644 index 00000000000..e578feed6d8 --- /dev/null +++ b/Documentation/block/cfq-iosched.txt | |||
@@ -0,0 +1,45 @@ | |||
1 | CFQ ioscheduler tunables | ||
2 | ======================== | ||
3 | |||
4 | slice_idle | ||
5 | ---------- | ||
6 | This specifies how long CFQ should idle for next request on certain cfq queues | ||
7 | (for sequential workloads) and service trees (for random workloads) before | ||
8 | queue is expired and CFQ selects next queue to dispatch from. | ||
9 | |||
10 | By default slice_idle is a non-zero value. That means by default we idle on | ||
11 | queues/service trees. This can be very helpful on highly seeky media like | ||
12 | single spindle SATA/SAS disks where we can cut down on overall number of | ||
13 | seeks and see improved throughput. | ||
14 | |||
15 | Setting slice_idle to 0 will remove all the idling on queues/service tree | ||
16 | level and one should see an overall improved throughput on faster storage | ||
17 | devices like multiple SATA/SAS disks in hardware RAID configuration. The down | ||
18 | side is that isolation provided from WRITES also goes down and notion of | ||
19 | IO priority becomes weaker. | ||
20 | |||
21 | So depending on storage and workload, it might be useful to set slice_idle=0. | ||
22 | In general I think for SATA/SAS disks and software RAID of SATA/SAS disks | ||
23 | keeping slice_idle enabled should be useful. For any configurations where | ||
24 | there are multiple spindles behind single LUN (Host based hardware RAID | ||
25 | controller or for storage arrays), setting slice_idle=0 might end up in better | ||
26 | throughput and acceptable latencies. | ||
27 | |||
28 | CFQ IOPS Mode for group scheduling | ||
29 | =================================== | ||
30 | Basic CFQ design is to provide priority based time slices. Higher priority | ||
31 | process gets bigger time slice and lower priority process gets smaller time | ||
32 | slice. Measuring time becomes harder if storage is fast and supports NCQ and | ||
33 | it would be better to dispatch multiple requests from multiple cfq queues in | ||
34 | request queue at a time. In such scenario, it is not possible to measure time | ||
35 | consumed by single queue accurately. | ||
36 | |||
37 | What is possible though is to measure number of requests dispatched from a | ||
38 | single queue and also allow dispatch from multiple cfq queue at the same time. | ||
39 | This effectively becomes the fairness in terms of IOPS (IO operations per | ||
40 | second). | ||
41 | |||
42 | If one sets slice_idle=0 and if storage supports NCQ, CFQ internally switches | ||
43 | to IOPS mode and starts providing fairness in terms of number of requests | ||
44 | dispatched. Note that this mode switching takes effect only for group | ||
45 | scheduling. For non-cgroup users nothing should change. | ||
diff --git a/Documentation/cgroups/blkio-controller.txt b/Documentation/cgroups/blkio-controller.txt index 48e0b21b005..6919d62591d 100644 --- a/Documentation/cgroups/blkio-controller.txt +++ b/Documentation/cgroups/blkio-controller.txt | |||
@@ -217,6 +217,7 @@ Details of cgroup files | |||
217 | CFQ sysfs tunable | 217 | CFQ sysfs tunable |
218 | ================= | 218 | ================= |
219 | /sys/block/<disk>/queue/iosched/group_isolation | 219 | /sys/block/<disk>/queue/iosched/group_isolation |
220 | ----------------------------------------------- | ||
220 | 221 | ||
221 | If group_isolation=1, it provides stronger isolation between groups at the | 222 | If group_isolation=1, it provides stronger isolation between groups at the |
222 | expense of throughput. By default group_isolation is 0. In general that | 223 | expense of throughput. By default group_isolation is 0. In general that |
@@ -243,6 +244,33 @@ By default one should run with group_isolation=0. If that is not sufficient | |||
243 | and one wants stronger isolation between groups, then set group_isolation=1 | 244 | and one wants stronger isolation between groups, then set group_isolation=1 |
244 | but this will come at cost of reduced throughput. | 245 | but this will come at cost of reduced throughput. |
245 | 246 | ||
247 | /sys/block/<disk>/queue/iosched/slice_idle | ||
248 | ------------------------------------------ | ||
249 | On a faster hardware CFQ can be slow, especially with sequential workload. | ||
250 | This happens because CFQ idles on a single queue and single queue might not | ||
251 | drive deeper request queue depths to keep the storage busy. In such scenarios | ||
252 | one can try setting slice_idle=0 and that would switch CFQ to IOPS | ||
253 | (IO operations per second) mode on NCQ supporting hardware. | ||
254 | |||
255 | That means CFQ will not idle between cfq queues of a cfq group and hence be | ||
256 | able to driver higher queue depth and achieve better throughput. That also | ||
257 | means that cfq provides fairness among groups in terms of IOPS and not in | ||
258 | terms of disk time. | ||
259 | |||
260 | /sys/block/<disk>/queue/iosched/group_idle | ||
261 | ------------------------------------------ | ||
262 | If one disables idling on individual cfq queues and cfq service trees by | ||
263 | setting slice_idle=0, group_idle kicks in. That means CFQ will still idle | ||
264 | on the group in an attempt to provide fairness among groups. | ||
265 | |||
266 | By default group_idle is same as slice_idle and does not do anything if | ||
267 | slice_idle is enabled. | ||
268 | |||
269 | One can experience an overall throughput drop if you have created multiple | ||
270 | groups and put applications in that group which are not driving enough | ||
271 | IO to keep disk busy. In that case set group_idle=0, and CFQ will not idle | ||
272 | on individual groups and throughput should improve. | ||
273 | |||
246 | What works | 274 | What works |
247 | ========== | 275 | ========== |
248 | - Currently only sync IO queues are support. All the buffered writes are | 276 | - Currently only sync IO queues are support. All the buffered writes are |
diff --git a/Documentation/gpio.txt b/Documentation/gpio.txt index d96a6dba574..9633da01ff4 100644 --- a/Documentation/gpio.txt +++ b/Documentation/gpio.txt | |||
@@ -109,17 +109,19 @@ use numbers 2000-2063 to identify GPIOs in a bank of I2C GPIO expanders. | |||
109 | 109 | ||
110 | If you want to initialize a structure with an invalid GPIO number, use | 110 | If you want to initialize a structure with an invalid GPIO number, use |
111 | some negative number (perhaps "-EINVAL"); that will never be valid. To | 111 | some negative number (perhaps "-EINVAL"); that will never be valid. To |
112 | test if a number could reference a GPIO, you may use this predicate: | 112 | test if such number from such a structure could reference a GPIO, you |
113 | may use this predicate: | ||
113 | 114 | ||
114 | int gpio_is_valid(int number); | 115 | int gpio_is_valid(int number); |
115 | 116 | ||
116 | A number that's not valid will be rejected by calls which may request | 117 | A number that's not valid will be rejected by calls which may request |
117 | or free GPIOs (see below). Other numbers may also be rejected; for | 118 | or free GPIOs (see below). Other numbers may also be rejected; for |
118 | example, a number might be valid but unused on a given board. | 119 | example, a number might be valid but temporarily unused on a given board. |
119 | |||
120 | Whether a platform supports multiple GPIO controllers is currently a | ||
121 | platform-specific implementation issue. | ||
122 | 120 | ||
121 | Whether a platform supports multiple GPIO controllers is a platform-specific | ||
122 | implementation issue, as are whether that support can leave "holes" in the space | ||
123 | of GPIO numbers, and whether new controllers can be added at runtime. Such issues | ||
124 | can affect things including whether adjacent GPIO numbers are both valid. | ||
123 | 125 | ||
124 | Using GPIOs | 126 | Using GPIOs |
125 | ----------- | 127 | ----------- |
@@ -480,12 +482,16 @@ To support this framework, a platform's Kconfig will "select" either | |||
480 | ARCH_REQUIRE_GPIOLIB or ARCH_WANT_OPTIONAL_GPIOLIB | 482 | ARCH_REQUIRE_GPIOLIB or ARCH_WANT_OPTIONAL_GPIOLIB |
481 | and arrange that its <asm/gpio.h> includes <asm-generic/gpio.h> and defines | 483 | and arrange that its <asm/gpio.h> includes <asm-generic/gpio.h> and defines |
482 | three functions: gpio_get_value(), gpio_set_value(), and gpio_cansleep(). | 484 | three functions: gpio_get_value(), gpio_set_value(), and gpio_cansleep(). |
483 | They may also want to provide a custom value for ARCH_NR_GPIOS. | ||
484 | 485 | ||
485 | ARCH_REQUIRE_GPIOLIB means that the gpio-lib code will always get compiled | 486 | It may also provide a custom value for ARCH_NR_GPIOS, so that it better |
487 | reflects the number of GPIOs in actual use on that platform, without | ||
488 | wasting static table space. (It should count both built-in/SoC GPIOs and | ||
489 | also ones on GPIO expanders. | ||
490 | |||
491 | ARCH_REQUIRE_GPIOLIB means that the gpiolib code will always get compiled | ||
486 | into the kernel on that architecture. | 492 | into the kernel on that architecture. |
487 | 493 | ||
488 | ARCH_WANT_OPTIONAL_GPIOLIB means the gpio-lib code defaults to off and the user | 494 | ARCH_WANT_OPTIONAL_GPIOLIB means the gpiolib code defaults to off and the user |
489 | can enable it and build it into the kernel optionally. | 495 | can enable it and build it into the kernel optionally. |
490 | 496 | ||
491 | If neither of these options are selected, the platform does not support | 497 | If neither of these options are selected, the platform does not support |
diff --git a/Documentation/hwmon/sysfs-interface b/Documentation/hwmon/sysfs-interface index ff45d1f837c..48ceabedf55 100644 --- a/Documentation/hwmon/sysfs-interface +++ b/Documentation/hwmon/sysfs-interface | |||
@@ -91,12 +91,11 @@ name The chip name. | |||
91 | I2C devices get this attribute created automatically. | 91 | I2C devices get this attribute created automatically. |
92 | RO | 92 | RO |
93 | 93 | ||
94 | update_rate The rate at which the chip will update readings. | 94 | update_interval The interval at which the chip will update readings. |
95 | Unit: millisecond | 95 | Unit: millisecond |
96 | RW | 96 | RW |
97 | Some devices have a variable update rate. This attribute | 97 | Some devices have a variable update rate or interval. |
98 | can be used to change the update rate to the desired | 98 | This attribute can be used to change it to the desired value. |
99 | frequency. | ||
100 | 99 | ||
101 | 100 | ||
102 | ************ | 101 | ************ |
diff --git a/Documentation/kernel-doc-nano-HOWTO.txt b/Documentation/kernel-doc-nano-HOWTO.txt index 27a52b35d55..3d8a97747f7 100644 --- a/Documentation/kernel-doc-nano-HOWTO.txt +++ b/Documentation/kernel-doc-nano-HOWTO.txt | |||
@@ -345,5 +345,10 @@ documentation, in <filename>, for the functions listed. | |||
345 | section titled <section title> from <filename>. | 345 | section titled <section title> from <filename>. |
346 | Spaces are allowed in <section title>; do not quote the <section title>. | 346 | Spaces are allowed in <section title>; do not quote the <section title>. |
347 | 347 | ||
348 | !C<filename> is replaced by nothing, but makes the tools check that | ||
349 | all DOC: sections and documented functions, symbols, etc. are used. | ||
350 | This makes sense to use when you use !F/!P only and want to verify | ||
351 | that all documentation is included. | ||
352 | |||
348 | Tim. | 353 | Tim. |
349 | */ <twaugh@redhat.com> | 354 | */ <twaugh@redhat.com> |
diff --git a/Documentation/mutex-design.txt b/Documentation/mutex-design.txt index c91ccc0720f..38c10fd7f41 100644 --- a/Documentation/mutex-design.txt +++ b/Documentation/mutex-design.txt | |||
@@ -9,7 +9,7 @@ firstly, there's nothing wrong with semaphores. But if the simpler | |||
9 | mutex semantics are sufficient for your code, then there are a couple | 9 | mutex semantics are sufficient for your code, then there are a couple |
10 | of advantages of mutexes: | 10 | of advantages of mutexes: |
11 | 11 | ||
12 | - 'struct mutex' is smaller on most architectures: .e.g on x86, | 12 | - 'struct mutex' is smaller on most architectures: E.g. on x86, |
13 | 'struct semaphore' is 20 bytes, 'struct mutex' is 16 bytes. | 13 | 'struct semaphore' is 20 bytes, 'struct mutex' is 16 bytes. |
14 | A smaller structure size means less RAM footprint, and better | 14 | A smaller structure size means less RAM footprint, and better |
15 | CPU-cache utilization. | 15 | CPU-cache utilization. |
@@ -136,3 +136,4 @@ the APIs of 'struct mutex' have been streamlined: | |||
136 | void mutex_lock_nested(struct mutex *lock, unsigned int subclass); | 136 | void mutex_lock_nested(struct mutex *lock, unsigned int subclass); |
137 | int mutex_lock_interruptible_nested(struct mutex *lock, | 137 | int mutex_lock_interruptible_nested(struct mutex *lock, |
138 | unsigned int subclass); | 138 | unsigned int subclass); |
139 | int atomic_dec_and_mutex_lock(atomic_t *cnt, struct mutex *lock); | ||
diff --git a/Documentation/networking/e1000.txt b/Documentation/networking/e1000.txt index 2df71861e57..d9271e74e48 100644 --- a/Documentation/networking/e1000.txt +++ b/Documentation/networking/e1000.txt | |||
@@ -1,82 +1,35 @@ | |||
1 | Linux* Base Driver for the Intel(R) PRO/1000 Family of Adapters | 1 | Linux* Base Driver for the Intel(R) PRO/1000 Family of Adapters |
2 | =============================================================== | 2 | =============================================================== |
3 | 3 | ||
4 | September 26, 2006 | 4 | Intel Gigabit Linux driver. |
5 | 5 | Copyright(c) 1999 - 2010 Intel Corporation. | |
6 | 6 | ||
7 | Contents | 7 | Contents |
8 | ======== | 8 | ======== |
9 | 9 | ||
10 | - In This Release | ||
11 | - Identifying Your Adapter | 10 | - Identifying Your Adapter |
12 | - Building and Installation | ||
13 | - Command Line Parameters | 11 | - Command Line Parameters |
14 | - Speed and Duplex Configuration | 12 | - Speed and Duplex Configuration |
15 | - Additional Configurations | 13 | - Additional Configurations |
16 | - Known Issues | ||
17 | - Support | 14 | - Support |
18 | 15 | ||
19 | |||
20 | In This Release | ||
21 | =============== | ||
22 | |||
23 | This file describes the Linux* Base Driver for the Intel(R) PRO/1000 Family | ||
24 | of Adapters. This driver includes support for Itanium(R)2-based systems. | ||
25 | |||
26 | For questions related to hardware requirements, refer to the documentation | ||
27 | supplied with your Intel PRO/1000 adapter. All hardware requirements listed | ||
28 | apply to use with Linux. | ||
29 | |||
30 | The following features are now available in supported kernels: | ||
31 | - Native VLANs | ||
32 | - Channel Bonding (teaming) | ||
33 | - SNMP | ||
34 | |||
35 | Channel Bonding documentation can be found in the Linux kernel source: | ||
36 | /Documentation/networking/bonding.txt | ||
37 | |||
38 | The driver information previously displayed in the /proc filesystem is not | ||
39 | supported in this release. Alternatively, you can use ethtool (version 1.6 | ||
40 | or later), lspci, and ifconfig to obtain the same information. | ||
41 | |||
42 | Instructions on updating ethtool can be found in the section "Additional | ||
43 | Configurations" later in this document. | ||
44 | |||
45 | NOTE: The Intel(R) 82562v 10/100 Network Connection only provides 10/100 | ||
46 | support. | ||
47 | |||
48 | |||
49 | Identifying Your Adapter | 16 | Identifying Your Adapter |
50 | ======================== | 17 | ======================== |
51 | 18 | ||
52 | For more information on how to identify your adapter, go to the Adapter & | 19 | For more information on how to identify your adapter, go to the Adapter & |
53 | Driver ID Guide at: | 20 | Driver ID Guide at: |
54 | 21 | ||
55 | http://support.intel.com/support/network/adapter/pro100/21397.htm | 22 | http://support.intel.com/support/go/network/adapter/idguide.htm |
56 | 23 | ||
57 | For the latest Intel network drivers for Linux, refer to the following | 24 | For the latest Intel network drivers for Linux, refer to the following |
58 | website. In the search field, enter your adapter name or type, or use the | 25 | website. In the search field, enter your adapter name or type, or use the |
59 | networking link on the left to search for your adapter: | 26 | networking link on the left to search for your adapter: |
60 | 27 | ||
61 | http://downloadfinder.intel.com/scripts-df/support_intel.asp | 28 | http://support.intel.com/support/go/network/adapter/home.htm |
62 | |||
63 | 29 | ||
64 | Command Line Parameters | 30 | Command Line Parameters |
65 | ======================= | 31 | ======================= |
66 | 32 | ||
67 | If the driver is built as a module, the following optional parameters | ||
68 | are used by entering them on the command line with the modprobe command | ||
69 | using this syntax: | ||
70 | |||
71 | modprobe e1000 [<option>=<VAL1>,<VAL2>,...] | ||
72 | |||
73 | For example, with two PRO/1000 PCI adapters, entering: | ||
74 | |||
75 | modprobe e1000 TxDescriptors=80,128 | ||
76 | |||
77 | loads the e1000 driver with 80 TX descriptors for the first adapter and | ||
78 | 128 TX descriptors for the second adapter. | ||
79 | |||
80 | The default value for each parameter is generally the recommended setting, | 33 | The default value for each parameter is generally the recommended setting, |
81 | unless otherwise noted. | 34 | unless otherwise noted. |
82 | 35 | ||
@@ -89,10 +42,6 @@ NOTES: For more information about the AutoNeg, Duplex, and Speed | |||
89 | parameters, see the application note at: | 42 | parameters, see the application note at: |
90 | http://www.intel.com/design/network/applnots/ap450.htm | 43 | http://www.intel.com/design/network/applnots/ap450.htm |
91 | 44 | ||
92 | A descriptor describes a data buffer and attributes related to | ||
93 | the data buffer. This information is accessed by the hardware. | ||
94 | |||
95 | |||
96 | AutoNeg | 45 | AutoNeg |
97 | ------- | 46 | ------- |
98 | (Supported only on adapters with copper connections) | 47 | (Supported only on adapters with copper connections) |
@@ -106,7 +55,6 @@ Duplex parameters must not be specified. | |||
106 | NOTE: Refer to the Speed and Duplex section of this readme for more | 55 | NOTE: Refer to the Speed and Duplex section of this readme for more |
107 | information on the AutoNeg parameter. | 56 | information on the AutoNeg parameter. |
108 | 57 | ||
109 | |||
110 | Duplex | 58 | Duplex |
111 | ------ | 59 | ------ |
112 | (Supported only on adapters with copper connections) | 60 | (Supported only on adapters with copper connections) |
@@ -119,7 +67,6 @@ set to auto-negotiate, the board auto-detects the correct duplex. If the | |||
119 | link partner is forced (either full or half), Duplex defaults to half- | 67 | link partner is forced (either full or half), Duplex defaults to half- |
120 | duplex. | 68 | duplex. |
121 | 69 | ||
122 | |||
123 | FlowControl | 70 | FlowControl |
124 | ----------- | 71 | ----------- |
125 | Valid Range: 0-3 (0=none, 1=Rx only, 2=Tx only, 3=Rx&Tx) | 72 | Valid Range: 0-3 (0=none, 1=Rx only, 2=Tx only, 3=Rx&Tx) |
@@ -128,16 +75,16 @@ Default Value: Reads flow control settings from the EEPROM | |||
128 | This parameter controls the automatic generation(Tx) and response(Rx) | 75 | This parameter controls the automatic generation(Tx) and response(Rx) |
129 | to Ethernet PAUSE frames. | 76 | to Ethernet PAUSE frames. |
130 | 77 | ||
131 | |||
132 | InterruptThrottleRate | 78 | InterruptThrottleRate |
133 | --------------------- | 79 | --------------------- |
134 | (not supported on Intel(R) 82542, 82543 or 82544-based adapters) | 80 | (not supported on Intel(R) 82542, 82543 or 82544-based adapters) |
135 | Valid Range: 0,1,3,100-100000 (0=off, 1=dynamic, 3=dynamic conservative) | 81 | Valid Range: 0,1,3,4,100-100000 (0=off, 1=dynamic, 3=dynamic conservative, |
82 | 4=simplified balancing) | ||
136 | Default Value: 3 | 83 | Default Value: 3 |
137 | 84 | ||
138 | The driver can limit the amount of interrupts per second that the adapter | 85 | The driver can limit the amount of interrupts per second that the adapter |
139 | will generate for incoming packets. It does this by writing a value to the | 86 | will generate for incoming packets. It does this by writing a value to the |
140 | adapter that is based on the maximum amount of interrupts that the adapter | 87 | adapter that is based on the maximum amount of interrupts that the adapter |
141 | will generate per second. | 88 | will generate per second. |
142 | 89 | ||
143 | Setting InterruptThrottleRate to a value greater or equal to 100 | 90 | Setting InterruptThrottleRate to a value greater or equal to 100 |
@@ -146,37 +93,43 @@ per second, even if more packets have come in. This reduces interrupt | |||
146 | load on the system and can lower CPU utilization under heavy load, | 93 | load on the system and can lower CPU utilization under heavy load, |
147 | but will increase latency as packets are not processed as quickly. | 94 | but will increase latency as packets are not processed as quickly. |
148 | 95 | ||
149 | The default behaviour of the driver previously assumed a static | 96 | The default behaviour of the driver previously assumed a static |
150 | InterruptThrottleRate value of 8000, providing a good fallback value for | 97 | InterruptThrottleRate value of 8000, providing a good fallback value for |
151 | all traffic types,but lacking in small packet performance and latency. | 98 | all traffic types,but lacking in small packet performance and latency. |
152 | The hardware can handle many more small packets per second however, and | 99 | The hardware can handle many more small packets per second however, and |
153 | for this reason an adaptive interrupt moderation algorithm was implemented. | 100 | for this reason an adaptive interrupt moderation algorithm was implemented. |
154 | 101 | ||
155 | Since 7.3.x, the driver has two adaptive modes (setting 1 or 3) in which | 102 | Since 7.3.x, the driver has two adaptive modes (setting 1 or 3) in which |
156 | it dynamically adjusts the InterruptThrottleRate value based on the traffic | 103 | it dynamically adjusts the InterruptThrottleRate value based on the traffic |
157 | that it receives. After determining the type of incoming traffic in the last | 104 | that it receives. After determining the type of incoming traffic in the last |
158 | timeframe, it will adjust the InterruptThrottleRate to an appropriate value | 105 | timeframe, it will adjust the InterruptThrottleRate to an appropriate value |
159 | for that traffic. | 106 | for that traffic. |
160 | 107 | ||
161 | The algorithm classifies the incoming traffic every interval into | 108 | The algorithm classifies the incoming traffic every interval into |
162 | classes. Once the class is determined, the InterruptThrottleRate value is | 109 | classes. Once the class is determined, the InterruptThrottleRate value is |
163 | adjusted to suit that traffic type the best. There are three classes defined: | 110 | adjusted to suit that traffic type the best. There are three classes defined: |
164 | "Bulk traffic", for large amounts of packets of normal size; "Low latency", | 111 | "Bulk traffic", for large amounts of packets of normal size; "Low latency", |
165 | for small amounts of traffic and/or a significant percentage of small | 112 | for small amounts of traffic and/or a significant percentage of small |
166 | packets; and "Lowest latency", for almost completely small packets or | 113 | packets; and "Lowest latency", for almost completely small packets or |
167 | minimal traffic. | 114 | minimal traffic. |
168 | 115 | ||
169 | In dynamic conservative mode, the InterruptThrottleRate value is set to 4000 | 116 | In dynamic conservative mode, the InterruptThrottleRate value is set to 4000 |
170 | for traffic that falls in class "Bulk traffic". If traffic falls in the "Low | 117 | for traffic that falls in class "Bulk traffic". If traffic falls in the "Low |
171 | latency" or "Lowest latency" class, the InterruptThrottleRate is increased | 118 | latency" or "Lowest latency" class, the InterruptThrottleRate is increased |
172 | stepwise to 20000. This default mode is suitable for most applications. | 119 | stepwise to 20000. This default mode is suitable for most applications. |
173 | 120 | ||
174 | For situations where low latency is vital such as cluster or | 121 | For situations where low latency is vital such as cluster or |
175 | grid computing, the algorithm can reduce latency even more when | 122 | grid computing, the algorithm can reduce latency even more when |
176 | InterruptThrottleRate is set to mode 1. In this mode, which operates | 123 | InterruptThrottleRate is set to mode 1. In this mode, which operates |
177 | the same as mode 3, the InterruptThrottleRate will be increased stepwise to | 124 | the same as mode 3, the InterruptThrottleRate will be increased stepwise to |
178 | 70000 for traffic in class "Lowest latency". | 125 | 70000 for traffic in class "Lowest latency". |
179 | 126 | ||
127 | In simplified mode the interrupt rate is based on the ratio of Tx and | ||
128 | Rx traffic. If the bytes per second rate is approximately equal, the | ||
129 | interrupt rate will drop as low as 2000 interrupts per second. If the | ||
130 | traffic is mostly transmit or mostly receive, the interrupt rate could | ||
131 | be as high as 8000. | ||
132 | |||
180 | Setting InterruptThrottleRate to 0 turns off any interrupt moderation | 133 | Setting InterruptThrottleRate to 0 turns off any interrupt moderation |
181 | and may improve small packet latency, but is generally not suitable | 134 | and may improve small packet latency, but is generally not suitable |
182 | for bulk throughput traffic. | 135 | for bulk throughput traffic. |
@@ -212,8 +165,6 @@ NOTE: When e1000 is loaded with default settings and multiple adapters | |||
212 | be platform-specific. If CPU utilization is not a concern, use | 165 | be platform-specific. If CPU utilization is not a concern, use |
213 | RX_POLLING (NAPI) and default driver settings. | 166 | RX_POLLING (NAPI) and default driver settings. |
214 | 167 | ||
215 | |||
216 | |||
217 | RxDescriptors | 168 | RxDescriptors |
218 | ------------- | 169 | ------------- |
219 | Valid Range: 80-256 for 82542 and 82543-based adapters | 170 | Valid Range: 80-256 for 82542 and 82543-based adapters |
@@ -225,15 +176,14 @@ by the driver. Increasing this value allows the driver to buffer more | |||
225 | incoming packets, at the expense of increased system memory utilization. | 176 | incoming packets, at the expense of increased system memory utilization. |
226 | 177 | ||
227 | Each descriptor is 16 bytes. A receive buffer is also allocated for each | 178 | Each descriptor is 16 bytes. A receive buffer is also allocated for each |
228 | descriptor and can be either 2048, 4096, 8192, or 16384 bytes, depending | 179 | descriptor and can be either 2048, 4096, 8192, or 16384 bytes, depending |
229 | on the MTU setting. The maximum MTU size is 16110. | 180 | on the MTU setting. The maximum MTU size is 16110. |
230 | 181 | ||
231 | NOTE: MTU designates the frame size. It only needs to be set for Jumbo | 182 | NOTE: MTU designates the frame size. It only needs to be set for Jumbo |
232 | Frames. Depending on the available system resources, the request | 183 | Frames. Depending on the available system resources, the request |
233 | for a higher number of receive descriptors may be denied. In this | 184 | for a higher number of receive descriptors may be denied. In this |
234 | case, use a lower number. | 185 | case, use a lower number. |
235 | 186 | ||
236 | |||
237 | RxIntDelay | 187 | RxIntDelay |
238 | ---------- | 188 | ---------- |
239 | Valid Range: 0-65535 (0=off) | 189 | Valid Range: 0-65535 (0=off) |
@@ -254,7 +204,6 @@ CAUTION: When setting RxIntDelay to a value other than 0, adapters may | |||
254 | restoring the network connection. To eliminate the potential | 204 | restoring the network connection. To eliminate the potential |
255 | for the hang ensure that RxIntDelay is set to 0. | 205 | for the hang ensure that RxIntDelay is set to 0. |
256 | 206 | ||
257 | |||
258 | RxAbsIntDelay | 207 | RxAbsIntDelay |
259 | ------------- | 208 | ------------- |
260 | (This parameter is supported only on 82540, 82545 and later adapters.) | 209 | (This parameter is supported only on 82540, 82545 and later adapters.) |
@@ -268,7 +217,6 @@ packet is received within the set amount of time. Proper tuning, | |||
268 | along with RxIntDelay, may improve traffic throughput in specific network | 217 | along with RxIntDelay, may improve traffic throughput in specific network |
269 | conditions. | 218 | conditions. |
270 | 219 | ||
271 | |||
272 | Speed | 220 | Speed |
273 | ----- | 221 | ----- |
274 | (This parameter is supported only on adapters with copper connections.) | 222 | (This parameter is supported only on adapters with copper connections.) |
@@ -280,7 +228,6 @@ Speed forces the line speed to the specified value in megabits per second | |||
280 | partner is set to auto-negotiate, the board will auto-detect the correct | 228 | partner is set to auto-negotiate, the board will auto-detect the correct |
281 | speed. Duplex should also be set when Speed is set to either 10 or 100. | 229 | speed. Duplex should also be set when Speed is set to either 10 or 100. |
282 | 230 | ||
283 | |||
284 | TxDescriptors | 231 | TxDescriptors |
285 | ------------- | 232 | ------------- |
286 | Valid Range: 80-256 for 82542 and 82543-based adapters | 233 | Valid Range: 80-256 for 82542 and 82543-based adapters |
@@ -295,6 +242,36 @@ NOTE: Depending on the available system resources, the request for a | |||
295 | higher number of transmit descriptors may be denied. In this case, | 242 | higher number of transmit descriptors may be denied. In this case, |
296 | use a lower number. | 243 | use a lower number. |
297 | 244 | ||
245 | TxDescriptorStep | ||
246 | ---------------- | ||
247 | Valid Range: 1 (use every Tx Descriptor) | ||
248 | 4 (use every 4th Tx Descriptor) | ||
249 | |||
250 | Default Value: 1 (use every Tx Descriptor) | ||
251 | |||
252 | On certain non-Intel architectures, it has been observed that intense TX | ||
253 | traffic bursts of short packets may result in an improper descriptor | ||
254 | writeback. If this occurs, the driver will report a "TX Timeout" and reset | ||
255 | the adapter, after which the transmit flow will restart, though data may | ||
256 | have stalled for as much as 10 seconds before it resumes. | ||
257 | |||
258 | The improper writeback does not occur on the first descriptor in a system | ||
259 | memory cache-line, which is typically 32 bytes, or 4 descriptors long. | ||
260 | |||
261 | Setting TxDescriptorStep to a value of 4 will ensure that all TX descriptors | ||
262 | are aligned to the start of a system memory cache line, and so this problem | ||
263 | will not occur. | ||
264 | |||
265 | NOTES: Setting TxDescriptorStep to 4 effectively reduces the number of | ||
266 | TxDescriptors available for transmits to 1/4 of the normal allocation. | ||
267 | This has a possible negative performance impact, which may be | ||
268 | compensated for by allocating more descriptors using the TxDescriptors | ||
269 | module parameter. | ||
270 | |||
271 | There are other conditions which may result in "TX Timeout", which will | ||
272 | not be resolved by the use of the TxDescriptorStep parameter. As the | ||
273 | issue addressed by this parameter has never been observed on Intel | ||
274 | Architecture platforms, it should not be used on Intel platforms. | ||
298 | 275 | ||
299 | TxIntDelay | 276 | TxIntDelay |
300 | ---------- | 277 | ---------- |
@@ -307,7 +284,6 @@ efficiency if properly tuned for specific network traffic. If the | |||
307 | system is reporting dropped transmits, this value may be set too high | 284 | system is reporting dropped transmits, this value may be set too high |
308 | causing the driver to run out of available transmit descriptors. | 285 | causing the driver to run out of available transmit descriptors. |
309 | 286 | ||
310 | |||
311 | TxAbsIntDelay | 287 | TxAbsIntDelay |
312 | ------------- | 288 | ------------- |
313 | (This parameter is supported only on 82540, 82545 and later adapters.) | 289 | (This parameter is supported only on 82540, 82545 and later adapters.) |
@@ -330,6 +306,35 @@ Default Value: 1 | |||
330 | A value of '1' indicates that the driver should enable IP checksum | 306 | A value of '1' indicates that the driver should enable IP checksum |
331 | offload for received packets (both UDP and TCP) to the adapter hardware. | 307 | offload for received packets (both UDP and TCP) to the adapter hardware. |
332 | 308 | ||
309 | Copybreak | ||
310 | --------- | ||
311 | Valid Range: 0-xxxxxxx (0=off) | ||
312 | Default Value: 256 | ||
313 | Usage: insmod e1000.ko copybreak=128 | ||
314 | |||
315 | Driver copies all packets below or equaling this size to a fresh Rx | ||
316 | buffer before handing it up the stack. | ||
317 | |||
318 | This parameter is different than other parameters, in that it is a | ||
319 | single (not 1,1,1 etc.) parameter applied to all driver instances and | ||
320 | it is also available during runtime at | ||
321 | /sys/module/e1000/parameters/copybreak | ||
322 | |||
323 | SmartPowerDownEnable | ||
324 | -------------------- | ||
325 | Valid Range: 0-1 | ||
326 | Default Value: 0 (disabled) | ||
327 | |||
328 | Allows PHY to turn off in lower power states. The user can turn off | ||
329 | this parameter in supported chipsets. | ||
330 | |||
331 | KumeranLockLoss | ||
332 | --------------- | ||
333 | Valid Range: 0-1 | ||
334 | Default Value: 1 (enabled) | ||
335 | |||
336 | This workaround skips resetting the PHY at shutdown for the initial | ||
337 | silicon releases of ICH8 systems. | ||
333 | 338 | ||
334 | Speed and Duplex Configuration | 339 | Speed and Duplex Configuration |
335 | ============================== | 340 | ============================== |
@@ -385,40 +390,9 @@ If the link partner is forced to a specific speed and duplex, then this | |||
385 | parameter should not be used. Instead, use the Speed and Duplex parameters | 390 | parameter should not be used. Instead, use the Speed and Duplex parameters |
386 | previously mentioned to force the adapter to the same speed and duplex. | 391 | previously mentioned to force the adapter to the same speed and duplex. |
387 | 392 | ||
388 | |||
389 | Additional Configurations | 393 | Additional Configurations |
390 | ========================= | 394 | ========================= |
391 | 395 | ||
392 | Configuring the Driver on Different Distributions | ||
393 | ------------------------------------------------- | ||
394 | Configuring a network driver to load properly when the system is started | ||
395 | is distribution dependent. Typically, the configuration process involves | ||
396 | adding an alias line to /etc/modules.conf or /etc/modprobe.conf as well | ||
397 | as editing other system startup scripts and/or configuration files. Many | ||
398 | popular Linux distributions ship with tools to make these changes for you. | ||
399 | To learn the proper way to configure a network device for your system, | ||
400 | refer to your distribution documentation. If during this process you are | ||
401 | asked for the driver or module name, the name for the Linux Base Driver | ||
402 | for the Intel(R) PRO/1000 Family of Adapters is e1000. | ||
403 | |||
404 | As an example, if you install the e1000 driver for two PRO/1000 adapters | ||
405 | (eth0 and eth1) and set the speed and duplex to 10full and 100half, add | ||
406 | the following to modules.conf or or modprobe.conf: | ||
407 | |||
408 | alias eth0 e1000 | ||
409 | alias eth1 e1000 | ||
410 | options e1000 Speed=10,100 Duplex=2,1 | ||
411 | |||
412 | Viewing Link Messages | ||
413 | --------------------- | ||
414 | Link messages will not be displayed to the console if the distribution is | ||
415 | restricting system messages. In order to see network driver link messages | ||
416 | on your console, set dmesg to eight by entering the following: | ||
417 | |||
418 | dmesg -n 8 | ||
419 | |||
420 | NOTE: This setting is not saved across reboots. | ||
421 | |||
422 | Jumbo Frames | 396 | Jumbo Frames |
423 | ------------ | 397 | ------------ |
424 | Jumbo Frames support is enabled by changing the MTU to a value larger than | 398 | Jumbo Frames support is enabled by changing the MTU to a value larger than |
@@ -437,9 +411,11 @@ Additional Configurations | |||
437 | setting in a different location. | 411 | setting in a different location. |
438 | 412 | ||
439 | Notes: | 413 | Notes: |
440 | 414 | Degradation in throughput performance may be observed in some Jumbo frames | |
441 | - To enable Jumbo Frames, increase the MTU size on the interface beyond | 415 | environments. If this is observed, increasing the application's socket buffer |
442 | 1500. | 416 | size and/or increasing the /proc/sys/net/ipv4/tcp_*mem entry values may help. |
417 | See the specific application manual and /usr/src/linux*/Documentation/ | ||
418 | networking/ip-sysctl.txt for more details. | ||
443 | 419 | ||
444 | - The maximum MTU setting for Jumbo Frames is 16110. This value coincides | 420 | - The maximum MTU setting for Jumbo Frames is 16110. This value coincides |
445 | with the maximum Jumbo Frames size of 16128. | 421 | with the maximum Jumbo Frames size of 16128. |
@@ -447,40 +423,11 @@ Additional Configurations | |||
447 | - Using Jumbo Frames at 10 or 100 Mbps may result in poor performance or | 423 | - Using Jumbo Frames at 10 or 100 Mbps may result in poor performance or |
448 | loss of link. | 424 | loss of link. |
449 | 425 | ||
450 | - Some Intel gigabit adapters that support Jumbo Frames have a frame size | ||
451 | limit of 9238 bytes, with a corresponding MTU size limit of 9216 bytes. | ||
452 | The adapters with this limitation are based on the Intel(R) 82571EB, | ||
453 | 82572EI, 82573L and 80003ES2LAN controller. These correspond to the | ||
454 | following product names: | ||
455 | Intel(R) PRO/1000 PT Server Adapter | ||
456 | Intel(R) PRO/1000 PT Desktop Adapter | ||
457 | Intel(R) PRO/1000 PT Network Connection | ||
458 | Intel(R) PRO/1000 PT Dual Port Server Adapter | ||
459 | Intel(R) PRO/1000 PT Dual Port Network Connection | ||
460 | Intel(R) PRO/1000 PF Server Adapter | ||
461 | Intel(R) PRO/1000 PF Network Connection | ||
462 | Intel(R) PRO/1000 PF Dual Port Server Adapter | ||
463 | Intel(R) PRO/1000 PB Server Connection | ||
464 | Intel(R) PRO/1000 PL Network Connection | ||
465 | Intel(R) PRO/1000 EB Network Connection with I/O Acceleration | ||
466 | Intel(R) PRO/1000 EB Backplane Connection with I/O Acceleration | ||
467 | Intel(R) PRO/1000 PT Quad Port Server Adapter | ||
468 | |||
469 | - Adapters based on the Intel(R) 82542 and 82573V/E controller do not | 426 | - Adapters based on the Intel(R) 82542 and 82573V/E controller do not |
470 | support Jumbo Frames. These correspond to the following product names: | 427 | support Jumbo Frames. These correspond to the following product names: |
471 | Intel(R) PRO/1000 Gigabit Server Adapter | 428 | Intel(R) PRO/1000 Gigabit Server Adapter |
472 | Intel(R) PRO/1000 PM Network Connection | 429 | Intel(R) PRO/1000 PM Network Connection |
473 | 430 | ||
474 | - The following adapters do not support Jumbo Frames: | ||
475 | Intel(R) 82562V 10/100 Network Connection | ||
476 | Intel(R) 82566DM Gigabit Network Connection | ||
477 | Intel(R) 82566DC Gigabit Network Connection | ||
478 | Intel(R) 82566MM Gigabit Network Connection | ||
479 | Intel(R) 82566MC Gigabit Network Connection | ||
480 | Intel(R) 82562GT 10/100 Network Connection | ||
481 | Intel(R) 82562G 10/100 Network Connection | ||
482 | |||
483 | |||
484 | Ethtool | 431 | Ethtool |
485 | ------- | 432 | ------- |
486 | The driver utilizes the ethtool interface for driver configuration and | 433 | The driver utilizes the ethtool interface for driver configuration and |
@@ -490,142 +437,14 @@ Additional Configurations | |||
490 | The latest release of ethtool can be found from | 437 | The latest release of ethtool can be found from |
491 | http://sourceforge.net/projects/gkernel. | 438 | http://sourceforge.net/projects/gkernel. |
492 | 439 | ||
493 | NOTE: Ethtool 1.6 only supports a limited set of ethtool options. Support | ||
494 | for a more complete ethtool feature set can be enabled by upgrading | ||
495 | ethtool to ethtool-1.8.1. | ||
496 | |||
497 | Enabling Wake on LAN* (WoL) | 440 | Enabling Wake on LAN* (WoL) |
498 | --------------------------- | 441 | --------------------------- |
499 | WoL is configured through the Ethtool* utility. Ethtool is included with | 442 | WoL is configured through the Ethtool* utility. |
500 | all versions of Red Hat after Red Hat 7.2. For other Linux distributions, | ||
501 | download and install Ethtool from the following website: | ||
502 | http://sourceforge.net/projects/gkernel. | ||
503 | |||
504 | For instructions on enabling WoL with Ethtool, refer to the website listed | ||
505 | above. | ||
506 | 443 | ||
507 | WoL will be enabled on the system during the next shut down or reboot. | 444 | WoL will be enabled on the system during the next shut down or reboot. |
508 | For this driver version, in order to enable WoL, the e1000 driver must be | 445 | For this driver version, in order to enable WoL, the e1000 driver must be |
509 | loaded when shutting down or rebooting the system. | 446 | loaded when shutting down or rebooting the system. |
510 | 447 | ||
511 | Wake On LAN is only supported on port A for the following devices: | ||
512 | Intel(R) PRO/1000 PT Dual Port Network Connection | ||
513 | Intel(R) PRO/1000 PT Dual Port Server Connection | ||
514 | Intel(R) PRO/1000 PT Dual Port Server Adapter | ||
515 | Intel(R) PRO/1000 PF Dual Port Server Adapter | ||
516 | Intel(R) PRO/1000 PT Quad Port Server Adapter | ||
517 | |||
518 | NAPI | ||
519 | ---- | ||
520 | NAPI (Rx polling mode) is enabled in the e1000 driver. | ||
521 | |||
522 | See www.cyberus.ca/~hadi/usenix-paper.tgz for more information on NAPI. | ||
523 | |||
524 | |||
525 | Known Issues | ||
526 | ============ | ||
527 | |||
528 | Dropped Receive Packets on Half-duplex 10/100 Networks | ||
529 | ------------------------------------------------------ | ||
530 | If you have an Intel PCI Express adapter running at 10mbps or 100mbps, half- | ||
531 | duplex, you may observe occasional dropped receive packets. There are no | ||
532 | workarounds for this problem in this network configuration. The network must | ||
533 | be updated to operate in full-duplex, and/or 1000mbps only. | ||
534 | |||
535 | Jumbo Frames System Requirement | ||
536 | ------------------------------- | ||
537 | Memory allocation failures have been observed on Linux systems with 64 MB | ||
538 | of RAM or less that are running Jumbo Frames. If you are using Jumbo | ||
539 | Frames, your system may require more than the advertised minimum | ||
540 | requirement of 64 MB of system memory. | ||
541 | |||
542 | Performance Degradation with Jumbo Frames | ||
543 | ----------------------------------------- | ||
544 | Degradation in throughput performance may be observed in some Jumbo frames | ||
545 | environments. If this is observed, increasing the application's socket | ||
546 | buffer size and/or increasing the /proc/sys/net/ipv4/tcp_*mem entry values | ||
547 | may help. See the specific application manual and | ||
548 | /usr/src/linux*/Documentation/ | ||
549 | networking/ip-sysctl.txt for more details. | ||
550 | |||
551 | Jumbo Frames on Foundry BigIron 8000 switch | ||
552 | ------------------------------------------- | ||
553 | There is a known issue using Jumbo frames when connected to a Foundry | ||
554 | BigIron 8000 switch. This is a 3rd party limitation. If you experience | ||
555 | loss of packets, lower the MTU size. | ||
556 | |||
557 | Allocating Rx Buffers when Using Jumbo Frames | ||
558 | --------------------------------------------- | ||
559 | Allocating Rx buffers when using Jumbo Frames on 2.6.x kernels may fail if | ||
560 | the available memory is heavily fragmented. This issue may be seen with PCI-X | ||
561 | adapters or with packet split disabled. This can be reduced or eliminated | ||
562 | by changing the amount of available memory for receive buffer allocation, by | ||
563 | increasing /proc/sys/vm/min_free_kbytes. | ||
564 | |||
565 | Multiple Interfaces on Same Ethernet Broadcast Network | ||
566 | ------------------------------------------------------ | ||
567 | Due to the default ARP behavior on Linux, it is not possible to have | ||
568 | one system on two IP networks in the same Ethernet broadcast domain | ||
569 | (non-partitioned switch) behave as expected. All Ethernet interfaces | ||
570 | will respond to IP traffic for any IP address assigned to the system. | ||
571 | This results in unbalanced receive traffic. | ||
572 | |||
573 | If you have multiple interfaces in a server, either turn on ARP | ||
574 | filtering by entering: | ||
575 | |||
576 | echo 1 > /proc/sys/net/ipv4/conf/all/arp_filter | ||
577 | (this only works if your kernel's version is higher than 2.4.5), | ||
578 | |||
579 | NOTE: This setting is not saved across reboots. The configuration | ||
580 | change can be made permanent by adding the line: | ||
581 | net.ipv4.conf.all.arp_filter = 1 | ||
582 | to the file /etc/sysctl.conf | ||
583 | |||
584 | or, | ||
585 | |||
586 | install the interfaces in separate broadcast domains (either in | ||
587 | different switches or in a switch partitioned to VLANs). | ||
588 | |||
589 | 82541/82547 can't link or are slow to link with some link partners | ||
590 | ----------------------------------------------------------------- | ||
591 | There is a known compatibility issue with 82541/82547 and some | ||
592 | low-end switches where the link will not be established, or will | ||
593 | be slow to establish. In particular, these switches are known to | ||
594 | be incompatible with 82541/82547: | ||
595 | |||
596 | Planex FXG-08TE | ||
597 | I-O Data ETG-SH8 | ||
598 | |||
599 | To workaround this issue, the driver can be compiled with an override | ||
600 | of the PHY's master/slave setting. Forcing master or forcing slave | ||
601 | mode will improve time-to-link. | ||
602 | |||
603 | # make CFLAGS_EXTRA=-DE1000_MASTER_SLAVE=<n> | ||
604 | |||
605 | Where <n> is: | ||
606 | |||
607 | 0 = Hardware default | ||
608 | 1 = Master mode | ||
609 | 2 = Slave mode | ||
610 | 3 = Auto master/slave | ||
611 | |||
612 | Disable rx flow control with ethtool | ||
613 | ------------------------------------ | ||
614 | In order to disable receive flow control using ethtool, you must turn | ||
615 | off auto-negotiation on the same command line. | ||
616 | |||
617 | For example: | ||
618 | |||
619 | ethtool -A eth? autoneg off rx off | ||
620 | |||
621 | Unplugging network cable while ethtool -p is running | ||
622 | ---------------------------------------------------- | ||
623 | In kernel versions 2.5.50 and later (including 2.6 kernel), unplugging | ||
624 | the network cable while ethtool -p is running will cause the system to | ||
625 | become unresponsive to keyboard commands, except for control-alt-delete. | ||
626 | Restarting the system appears to be the only remedy. | ||
627 | |||
628 | |||
629 | Support | 448 | Support |
630 | ======= | 449 | ======= |
631 | 450 | ||
diff --git a/Documentation/networking/e1000e.txt b/Documentation/networking/e1000e.txt new file mode 100644 index 00000000000..6aa048badf3 --- /dev/null +++ b/Documentation/networking/e1000e.txt | |||
@@ -0,0 +1,302 @@ | |||
1 | Linux* Driver for Intel(R) Network Connection | ||
2 | =============================================================== | ||
3 | |||
4 | Intel Gigabit Linux driver. | ||
5 | Copyright(c) 1999 - 2010 Intel Corporation. | ||
6 | |||
7 | Contents | ||
8 | ======== | ||
9 | |||
10 | - Identifying Your Adapter | ||
11 | - Command Line Parameters | ||
12 | - Additional Configurations | ||
13 | - Support | ||
14 | |||
15 | Identifying Your Adapter | ||
16 | ======================== | ||
17 | |||
18 | The e1000e driver supports all PCI Express Intel(R) Gigabit Network | ||
19 | Connections, except those that are 82575, 82576 and 82580-based*. | ||
20 | |||
21 | * NOTE: The Intel(R) PRO/1000 P Dual Port Server Adapter is supported by | ||
22 | the e1000 driver, not the e1000e driver due to the 82546 part being used | ||
23 | behind a PCI Express bridge. | ||
24 | |||
25 | For more information on how to identify your adapter, go to the Adapter & | ||
26 | Driver ID Guide at: | ||
27 | |||
28 | http://support.intel.com/support/go/network/adapter/idguide.htm | ||
29 | |||
30 | For the latest Intel network drivers for Linux, refer to the following | ||
31 | website. In the search field, enter your adapter name or type, or use the | ||
32 | networking link on the left to search for your adapter: | ||
33 | |||
34 | http://support.intel.com/support/go/network/adapter/home.htm | ||
35 | |||
36 | Command Line Parameters | ||
37 | ======================= | ||
38 | |||
39 | The default value for each parameter is generally the recommended setting, | ||
40 | unless otherwise noted. | ||
41 | |||
42 | NOTES: For more information about the InterruptThrottleRate, | ||
43 | RxIntDelay, TxIntDelay, RxAbsIntDelay, and TxAbsIntDelay | ||
44 | parameters, see the application note at: | ||
45 | http://www.intel.com/design/network/applnots/ap450.htm | ||
46 | |||
47 | InterruptThrottleRate | ||
48 | --------------------- | ||
49 | Valid Range: 0,1,3,4,100-100000 (0=off, 1=dynamic, 3=dynamic conservative, | ||
50 | 4=simplified balancing) | ||
51 | Default Value: 3 | ||
52 | |||
53 | The driver can limit the amount of interrupts per second that the adapter | ||
54 | will generate for incoming packets. It does this by writing a value to the | ||
55 | adapter that is based on the maximum amount of interrupts that the adapter | ||
56 | will generate per second. | ||
57 | |||
58 | Setting InterruptThrottleRate to a value greater or equal to 100 | ||
59 | will program the adapter to send out a maximum of that many interrupts | ||
60 | per second, even if more packets have come in. This reduces interrupt | ||
61 | load on the system and can lower CPU utilization under heavy load, | ||
62 | but will increase latency as packets are not processed as quickly. | ||
63 | |||
64 | The driver has two adaptive modes (setting 1 or 3) in which | ||
65 | it dynamically adjusts the InterruptThrottleRate value based on the traffic | ||
66 | that it receives. After determining the type of incoming traffic in the last | ||
67 | timeframe, it will adjust the InterruptThrottleRate to an appropriate value | ||
68 | for that traffic. | ||
69 | |||
70 | The algorithm classifies the incoming traffic every interval into | ||
71 | classes. Once the class is determined, the InterruptThrottleRate value is | ||
72 | adjusted to suit that traffic type the best. There are three classes defined: | ||
73 | "Bulk traffic", for large amounts of packets of normal size; "Low latency", | ||
74 | for small amounts of traffic and/or a significant percentage of small | ||
75 | packets; and "Lowest latency", for almost completely small packets or | ||
76 | minimal traffic. | ||
77 | |||
78 | In dynamic conservative mode, the InterruptThrottleRate value is set to 4000 | ||
79 | for traffic that falls in class "Bulk traffic". If traffic falls in the "Low | ||
80 | latency" or "Lowest latency" class, the InterruptThrottleRate is increased | ||
81 | stepwise to 20000. This default mode is suitable for most applications. | ||
82 | |||
83 | For situations where low latency is vital such as cluster or | ||
84 | grid computing, the algorithm can reduce latency even more when | ||
85 | InterruptThrottleRate is set to mode 1. In this mode, which operates | ||
86 | the same as mode 3, the InterruptThrottleRate will be increased stepwise to | ||
87 | 70000 for traffic in class "Lowest latency". | ||
88 | |||
89 | In simplified mode the interrupt rate is based on the ratio of Tx and | ||
90 | Rx traffic. If the bytes per second rate is approximately equal the | ||
91 | interrupt rate will drop as low as 2000 interrupts per second. If the | ||
92 | traffic is mostly transmit or mostly receive, the interrupt rate could | ||
93 | be as high as 8000. | ||
94 | |||
95 | Setting InterruptThrottleRate to 0 turns off any interrupt moderation | ||
96 | and may improve small packet latency, but is generally not suitable | ||
97 | for bulk throughput traffic. | ||
98 | |||
99 | NOTE: InterruptThrottleRate takes precedence over the TxAbsIntDelay and | ||
100 | RxAbsIntDelay parameters. In other words, minimizing the receive | ||
101 | and/or transmit absolute delays does not force the controller to | ||
102 | generate more interrupts than what the Interrupt Throttle Rate | ||
103 | allows. | ||
104 | |||
105 | NOTE: When e1000e is loaded with default settings and multiple adapters | ||
106 | are in use simultaneously, the CPU utilization may increase non- | ||
107 | linearly. In order to limit the CPU utilization without impacting | ||
108 | the overall throughput, we recommend that you load the driver as | ||
109 | follows: | ||
110 | |||
111 | modprobe e1000e InterruptThrottleRate=3000,3000,3000 | ||
112 | |||
113 | This sets the InterruptThrottleRate to 3000 interrupts/sec for | ||
114 | the first, second, and third instances of the driver. The range | ||
115 | of 2000 to 3000 interrupts per second works on a majority of | ||
116 | systems and is a good starting point, but the optimal value will | ||
117 | be platform-specific. If CPU utilization is not a concern, use | ||
118 | RX_POLLING (NAPI) and default driver settings. | ||
119 | |||
120 | RxIntDelay | ||
121 | ---------- | ||
122 | Valid Range: 0-65535 (0=off) | ||
123 | Default Value: 0 | ||
124 | |||
125 | This value delays the generation of receive interrupts in units of 1.024 | ||
126 | microseconds. Receive interrupt reduction can improve CPU efficiency if | ||
127 | properly tuned for specific network traffic. Increasing this value adds | ||
128 | extra latency to frame reception and can end up decreasing the throughput | ||
129 | of TCP traffic. If the system is reporting dropped receives, this value | ||
130 | may be set too high, causing the driver to run out of available receive | ||
131 | descriptors. | ||
132 | |||
133 | CAUTION: When setting RxIntDelay to a value other than 0, adapters may | ||
134 | hang (stop transmitting) under certain network conditions. If | ||
135 | this occurs a NETDEV WATCHDOG message is logged in the system | ||
136 | event log. In addition, the controller is automatically reset, | ||
137 | restoring the network connection. To eliminate the potential | ||
138 | for the hang ensure that RxIntDelay is set to 0. | ||
139 | |||
140 | RxAbsIntDelay | ||
141 | ------------- | ||
142 | Valid Range: 0-65535 (0=off) | ||
143 | Default Value: 8 | ||
144 | |||
145 | This value, in units of 1.024 microseconds, limits the delay in which a | ||
146 | receive interrupt is generated. Useful only if RxIntDelay is non-zero, | ||
147 | this value ensures that an interrupt is generated after the initial | ||
148 | packet is received within the set amount of time. Proper tuning, | ||
149 | along with RxIntDelay, may improve traffic throughput in specific network | ||
150 | conditions. | ||
151 | |||
152 | TxIntDelay | ||
153 | ---------- | ||
154 | Valid Range: 0-65535 (0=off) | ||
155 | Default Value: 8 | ||
156 | |||
157 | This value delays the generation of transmit interrupts in units of | ||
158 | 1.024 microseconds. Transmit interrupt reduction can improve CPU | ||
159 | efficiency if properly tuned for specific network traffic. If the | ||
160 | system is reporting dropped transmits, this value may be set too high | ||
161 | causing the driver to run out of available transmit descriptors. | ||
162 | |||
163 | TxAbsIntDelay | ||
164 | ------------- | ||
165 | Valid Range: 0-65535 (0=off) | ||
166 | Default Value: 32 | ||
167 | |||
168 | This value, in units of 1.024 microseconds, limits the delay in which a | ||
169 | transmit interrupt is generated. Useful only if TxIntDelay is non-zero, | ||
170 | this value ensures that an interrupt is generated after the initial | ||
171 | packet is sent on the wire within the set amount of time. Proper tuning, | ||
172 | along with TxIntDelay, may improve traffic throughput in specific | ||
173 | network conditions. | ||
174 | |||
175 | Copybreak | ||
176 | --------- | ||
177 | Valid Range: 0-xxxxxxx (0=off) | ||
178 | Default Value: 256 | ||
179 | |||
180 | Driver copies all packets below or equaling this size to a fresh Rx | ||
181 | buffer before handing it up the stack. | ||
182 | |||
183 | This parameter is different than other parameters, in that it is a | ||
184 | single (not 1,1,1 etc.) parameter applied to all driver instances and | ||
185 | it is also available during runtime at | ||
186 | /sys/module/e1000e/parameters/copybreak | ||
187 | |||
188 | SmartPowerDownEnable | ||
189 | -------------------- | ||
190 | Valid Range: 0-1 | ||
191 | Default Value: 0 (disabled) | ||
192 | |||
193 | Allows PHY to turn off in lower power states. The user can set this parameter | ||
194 | in supported chipsets. | ||
195 | |||
196 | KumeranLockLoss | ||
197 | --------------- | ||
198 | Valid Range: 0-1 | ||
199 | Default Value: 1 (enabled) | ||
200 | |||
201 | This workaround skips resetting the PHY at shutdown for the initial | ||
202 | silicon releases of ICH8 systems. | ||
203 | |||
204 | IntMode | ||
205 | ------- | ||
206 | Valid Range: 0-2 (0=legacy, 1=MSI, 2=MSI-X) | ||
207 | Default Value: 2 | ||
208 | |||
209 | Allows changing the interrupt mode at module load time, without requiring a | ||
210 | recompile. If the driver load fails to enable a specific interrupt mode, the | ||
211 | driver will try other interrupt modes, from least to most compatible. The | ||
212 | interrupt order is MSI-X, MSI, Legacy. If specifying MSI (IntMode=1) | ||
213 | interrupts, only MSI and Legacy will be attempted. | ||
214 | |||
215 | CrcStripping | ||
216 | ------------ | ||
217 | Valid Range: 0-1 | ||
218 | Default Value: 1 (enabled) | ||
219 | |||
220 | Strip the CRC from received packets before sending up the network stack. If | ||
221 | you have a machine with a BMC enabled but cannot receive IPMI traffic after | ||
222 | loading or enabling the driver, try disabling this feature. | ||
223 | |||
224 | WriteProtectNVM | ||
225 | --------------- | ||
226 | Valid Range: 0-1 | ||
227 | Default Value: 1 (enabled) | ||
228 | |||
229 | Set the hardware to ignore all write/erase cycles to the GbE region in the | ||
230 | ICHx NVM (non-volatile memory). This feature can be disabled by the | ||
231 | WriteProtectNVM module parameter (enabled by default) only after a hardware | ||
232 | reset, but the machine must be power cycled before trying to enable writes. | ||
233 | |||
234 | Note: the kernel boot option iomem=relaxed may need to be set if the kernel | ||
235 | config option CONFIG_STRICT_DEVMEM=y, if the root user wants to write the | ||
236 | NVM from user space via ethtool. | ||
237 | |||
238 | Additional Configurations | ||
239 | ========================= | ||
240 | |||
241 | Jumbo Frames | ||
242 | ------------ | ||
243 | Jumbo Frames support is enabled by changing the MTU to a value larger than | ||
244 | the default of 1500. Use the ifconfig command to increase the MTU size. | ||
245 | For example: | ||
246 | |||
247 | ifconfig eth<x> mtu 9000 up | ||
248 | |||
249 | This setting is not saved across reboots. | ||
250 | |||
251 | Notes: | ||
252 | |||
253 | - The maximum MTU setting for Jumbo Frames is 9216. This value coincides | ||
254 | with the maximum Jumbo Frames size of 9234 bytes. | ||
255 | |||
256 | - Using Jumbo Frames at 10 or 100 Mbps is not supported and may result in | ||
257 | poor performance or loss of link. | ||
258 | |||
259 | - Some adapters limit Jumbo Frames sized packets to a maximum of | ||
260 | 4096 bytes and some adapters do not support Jumbo Frames. | ||
261 | |||
262 | |||
263 | Ethtool | ||
264 | ------- | ||
265 | The driver utilizes the ethtool interface for driver configuration and | ||
266 | diagnostics, as well as displaying statistical information. We | ||
267 | strongly recommend downloading the latest version of Ethtool at: | ||
268 | |||
269 | http://sourceforge.net/projects/gkernel. | ||
270 | |||
271 | Speed and Duplex | ||
272 | ---------------- | ||
273 | Speed and Duplex are configured through the Ethtool* utility. For | ||
274 | instructions, refer to the Ethtool man page. | ||
275 | |||
276 | Enabling Wake on LAN* (WoL) | ||
277 | --------------------------- | ||
278 | WoL is configured through the Ethtool* utility. For instructions on | ||
279 | enabling WoL with Ethtool, refer to the Ethtool man page. | ||
280 | |||
281 | WoL will be enabled on the system during the next shut down or reboot. | ||
282 | For this driver version, in order to enable WoL, the e1000e driver must be | ||
283 | loaded when shutting down or rebooting the system. | ||
284 | |||
285 | In most cases Wake On LAN is only supported on port A for multiple port | ||
286 | adapters. To verify if a port supports Wake on LAN run ethtool eth<X>. | ||
287 | |||
288 | |||
289 | Support | ||
290 | ======= | ||
291 | |||
292 | For general information, go to the Intel support website at: | ||
293 | |||
294 | www.intel.com/support/ | ||
295 | |||
296 | or the Intel Wired Networking project hosted by Sourceforge at: | ||
297 | |||
298 | http://sourceforge.net/projects/e1000 | ||
299 | |||
300 | If an issue is identified with the released source code on the supported | ||
301 | kernel with a supported adapter, email the specific information related | ||
302 | to the issue to e1000-devel@lists.sf.net | ||
diff --git a/Documentation/networking/ixgbevf.txt b/Documentation/networking/ixgbevf.txt index 19015de6725..21dd5d15b6b 100755..100644 --- a/Documentation/networking/ixgbevf.txt +++ b/Documentation/networking/ixgbevf.txt | |||
@@ -1,19 +1,16 @@ | |||
1 | Linux* Base Driver for Intel(R) Network Connection | 1 | Linux* Base Driver for Intel(R) Network Connection |
2 | ================================================== | 2 | ================================================== |
3 | 3 | ||
4 | November 24, 2009 | 4 | Intel Gigabit Linux driver. |
5 | Copyright(c) 1999 - 2010 Intel Corporation. | ||
5 | 6 | ||
6 | Contents | 7 | Contents |
7 | ======== | 8 | ======== |
8 | 9 | ||
9 | - In This Release | ||
10 | - Identifying Your Adapter | 10 | - Identifying Your Adapter |
11 | - Known Issues/Troubleshooting | 11 | - Known Issues/Troubleshooting |
12 | - Support | 12 | - Support |
13 | 13 | ||
14 | In This Release | ||
15 | =============== | ||
16 | |||
17 | This file describes the ixgbevf Linux* Base Driver for Intel Network | 14 | This file describes the ixgbevf Linux* Base Driver for Intel Network |
18 | Connection. | 15 | Connection. |
19 | 16 | ||
@@ -33,7 +30,7 @@ Identifying Your Adapter | |||
33 | For more information on how to identify your adapter, go to the Adapter & | 30 | For more information on how to identify your adapter, go to the Adapter & |
34 | Driver ID Guide at: | 31 | Driver ID Guide at: |
35 | 32 | ||
36 | http://support.intel.com/support/network/sb/CS-008441.htm | 33 | http://support.intel.com/support/go/network/adapter/idguide.htm |
37 | 34 | ||
38 | Known Issues/Troubleshooting | 35 | Known Issues/Troubleshooting |
39 | ============================ | 36 | ============================ |
@@ -57,34 +54,3 @@ or the Intel Wired Networking project hosted by Sourceforge at: | |||
57 | If an issue is identified with the released source code on the supported | 54 | If an issue is identified with the released source code on the supported |
58 | kernel with a supported adapter, email the specific information related | 55 | kernel with a supported adapter, email the specific information related |
59 | to the issue to e1000-devel@lists.sf.net | 56 | to the issue to e1000-devel@lists.sf.net |
60 | |||
61 | License | ||
62 | ======= | ||
63 | |||
64 | Intel 10 Gigabit Linux driver. | ||
65 | Copyright(c) 1999 - 2009 Intel Corporation. | ||
66 | |||
67 | This program is free software; you can redistribute it and/or modify it | ||
68 | under the terms and conditions of the GNU General Public License, | ||
69 | version 2, as published by the Free Software Foundation. | ||
70 | |||
71 | This program is distributed in the hope it will be useful, but WITHOUT | ||
72 | ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | ||
73 | FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for | ||
74 | more details. | ||
75 | |||
76 | You should have received a copy of the GNU General Public License along with | ||
77 | this program; if not, write to the Free Software Foundation, Inc., | ||
78 | 51 Franklin St - Fifth Floor, Boston, MA 02110-1301 USA. | ||
79 | |||
80 | The full GNU General Public License is included in this distribution in | ||
81 | the file called "COPYING". | ||
82 | |||
83 | Trademarks | ||
84 | ========== | ||
85 | |||
86 | Intel, Itanium, and Pentium are trademarks or registered trademarks of | ||
87 | Intel Corporation or its subsidiaries in the United States and other | ||
88 | countries. | ||
89 | |||
90 | * Other names and brands may be claimed as the property of others. | ||
diff --git a/Documentation/power/regulator/overview.txt b/Documentation/power/regulator/overview.txt index 9363e056188..8ed17587a74 100644 --- a/Documentation/power/regulator/overview.txt +++ b/Documentation/power/regulator/overview.txt | |||
@@ -13,7 +13,7 @@ regulators (where voltage output is controllable) and current sinks (where | |||
13 | current limit is controllable). | 13 | current limit is controllable). |
14 | 14 | ||
15 | (C) 2008 Wolfson Microelectronics PLC. | 15 | (C) 2008 Wolfson Microelectronics PLC. |
16 | Author: Liam Girdwood <lg@opensource.wolfsonmicro.com> | 16 | Author: Liam Girdwood <lrg@slimlogic.co.uk> |
17 | 17 | ||
18 | 18 | ||
19 | Nomenclature | 19 | Nomenclature |
diff --git a/Documentation/sound/alsa/HD-Audio-Models.txt b/Documentation/sound/alsa/HD-Audio-Models.txt index ce46fa1e643..37c6aad5e59 100644 --- a/Documentation/sound/alsa/HD-Audio-Models.txt +++ b/Documentation/sound/alsa/HD-Audio-Models.txt | |||
@@ -296,6 +296,7 @@ Conexant 5051 | |||
296 | Conexant 5066 | 296 | Conexant 5066 |
297 | ============= | 297 | ============= |
298 | laptop Basic Laptop config (default) | 298 | laptop Basic Laptop config (default) |
299 | hp-laptop HP laptops, e g G60 | ||
299 | dell-laptop Dell laptops | 300 | dell-laptop Dell laptops |
300 | dell-vostro Dell Vostro | 301 | dell-vostro Dell Vostro |
301 | olpc-xo-1_5 OLPC XO 1.5 | 302 | olpc-xo-1_5 OLPC XO 1.5 |
diff --git a/Documentation/workqueue.txt b/Documentation/workqueue.txt new file mode 100644 index 00000000000..e4498a2872c --- /dev/null +++ b/Documentation/workqueue.txt | |||
@@ -0,0 +1,380 @@ | |||
1 | |||
2 | Concurrency Managed Workqueue (cmwq) | ||
3 | |||
4 | September, 2010 Tejun Heo <tj@kernel.org> | ||
5 | Florian Mickler <florian@mickler.org> | ||
6 | |||
7 | CONTENTS | ||
8 | |||
9 | 1. Introduction | ||
10 | 2. Why cmwq? | ||
11 | 3. The Design | ||
12 | 4. Application Programming Interface (API) | ||
13 | 5. Example Execution Scenarios | ||
14 | 6. Guidelines | ||
15 | |||
16 | |||
17 | 1. Introduction | ||
18 | |||
19 | There are many cases where an asynchronous process execution context | ||
20 | is needed and the workqueue (wq) API is the most commonly used | ||
21 | mechanism for such cases. | ||
22 | |||
23 | When such an asynchronous execution context is needed, a work item | ||
24 | describing which function to execute is put on a queue. An | ||
25 | independent thread serves as the asynchronous execution context. The | ||
26 | queue is called workqueue and the thread is called worker. | ||
27 | |||
28 | While there are work items on the workqueue the worker executes the | ||
29 | functions associated with the work items one after the other. When | ||
30 | there is no work item left on the workqueue the worker becomes idle. | ||
31 | When a new work item gets queued, the worker begins executing again. | ||
32 | |||
33 | |||
34 | 2. Why cmwq? | ||
35 | |||
36 | In the original wq implementation, a multi threaded (MT) wq had one | ||
37 | worker thread per CPU and a single threaded (ST) wq had one worker | ||
38 | thread system-wide. A single MT wq needed to keep around the same | ||
39 | number of workers as the number of CPUs. The kernel grew a lot of MT | ||
40 | wq users over the years and with the number of CPU cores continuously | ||
41 | rising, some systems saturated the default 32k PID space just booting | ||
42 | up. | ||
43 | |||
44 | Although MT wq wasted a lot of resource, the level of concurrency | ||
45 | provided was unsatisfactory. The limitation was common to both ST and | ||
46 | MT wq albeit less severe on MT. Each wq maintained its own separate | ||
47 | worker pool. A MT wq could provide only one execution context per CPU | ||
48 | while a ST wq one for the whole system. Work items had to compete for | ||
49 | those very limited execution contexts leading to various problems | ||
50 | including proneness to deadlocks around the single execution context. | ||
51 | |||
52 | The tension between the provided level of concurrency and resource | ||
53 | usage also forced its users to make unnecessary tradeoffs like libata | ||
54 | choosing to use ST wq for polling PIOs and accepting an unnecessary | ||
55 | limitation that no two polling PIOs can progress at the same time. As | ||
56 | MT wq don't provide much better concurrency, users which require | ||
57 | higher level of concurrency, like async or fscache, had to implement | ||
58 | their own thread pool. | ||
59 | |||
60 | Concurrency Managed Workqueue (cmwq) is a reimplementation of wq with | ||
61 | focus on the following goals. | ||
62 | |||
63 | * Maintain compatibility with the original workqueue API. | ||
64 | |||
65 | * Use per-CPU unified worker pools shared by all wq to provide | ||
66 | flexible level of concurrency on demand without wasting a lot of | ||
67 | resource. | ||
68 | |||
69 | * Automatically regulate worker pool and level of concurrency so that | ||
70 | the API users don't need to worry about such details. | ||
71 | |||
72 | |||
73 | 3. The Design | ||
74 | |||
75 | In order to ease the asynchronous execution of functions a new | ||
76 | abstraction, the work item, is introduced. | ||
77 | |||
78 | A work item is a simple struct that holds a pointer to the function | ||
79 | that is to be executed asynchronously. Whenever a driver or subsystem | ||
80 | wants a function to be executed asynchronously it has to set up a work | ||
81 | item pointing to that function and queue that work item on a | ||
82 | workqueue. | ||
83 | |||
84 | Special purpose threads, called worker threads, execute the functions | ||
85 | off of the queue, one after the other. If no work is queued, the | ||
86 | worker threads become idle. These worker threads are managed in so | ||
87 | called thread-pools. | ||
88 | |||
89 | The cmwq design differentiates between the user-facing workqueues that | ||
90 | subsystems and drivers queue work items on and the backend mechanism | ||
91 | which manages thread-pool and processes the queued work items. | ||
92 | |||
93 | The backend is called gcwq. There is one gcwq for each possible CPU | ||
94 | and one gcwq to serve work items queued on unbound workqueues. | ||
95 | |||
96 | Subsystems and drivers can create and queue work items through special | ||
97 | workqueue API functions as they see fit. They can influence some | ||
98 | aspects of the way the work items are executed by setting flags on the | ||
99 | workqueue they are putting the work item on. These flags include | ||
100 | things like CPU locality, reentrancy, concurrency limits and more. To | ||
101 | get a detailed overview refer to the API description of | ||
102 | alloc_workqueue() below. | ||
103 | |||
104 | When a work item is queued to a workqueue, the target gcwq is | ||
105 | determined according to the queue parameters and workqueue attributes | ||
106 | and appended on the shared worklist of the gcwq. For example, unless | ||
107 | specifically overridden, a work item of a bound workqueue will be | ||
108 | queued on the worklist of exactly that gcwq that is associated to the | ||
109 | CPU the issuer is running on. | ||
110 | |||
111 | For any worker pool implementation, managing the concurrency level | ||
112 | (how many execution contexts are active) is an important issue. cmwq | ||
113 | tries to keep the concurrency at a minimal but sufficient level. | ||
114 | Minimal to save resources and sufficient in that the system is used at | ||
115 | its full capacity. | ||
116 | |||
117 | Each gcwq bound to an actual CPU implements concurrency management by | ||
118 | hooking into the scheduler. The gcwq is notified whenever an active | ||
119 | worker wakes up or sleeps and keeps track of the number of the | ||
120 | currently runnable workers. Generally, work items are not expected to | ||
121 | hog a CPU and consume many cycles. That means maintaining just enough | ||
122 | concurrency to prevent work processing from stalling should be | ||
123 | optimal. As long as there are one or more runnable workers on the | ||
124 | CPU, the gcwq doesn't start execution of a new work, but, when the | ||
125 | last running worker goes to sleep, it immediately schedules a new | ||
126 | worker so that the CPU doesn't sit idle while there are pending work | ||
127 | items. This allows using a minimal number of workers without losing | ||
128 | execution bandwidth. | ||
129 | |||
130 | Keeping idle workers around doesn't cost other than the memory space | ||
131 | for kthreads, so cmwq holds onto idle ones for a while before killing | ||
132 | them. | ||
133 | |||
134 | For an unbound wq, the above concurrency management doesn't apply and | ||
135 | the gcwq for the pseudo unbound CPU tries to start executing all work | ||
136 | items as soon as possible. The responsibility of regulating | ||
137 | concurrency level is on the users. There is also a flag to mark a | ||
138 | bound wq to ignore the concurrency management. Please refer to the | ||
139 | API section for details. | ||
140 | |||
141 | Forward progress guarantee relies on that workers can be created when | ||
142 | more execution contexts are necessary, which in turn is guaranteed | ||
143 | through the use of rescue workers. All work items which might be used | ||
144 | on code paths that handle memory reclaim are required to be queued on | ||
145 | wq's that have a rescue-worker reserved for execution under memory | ||
146 | pressure. Else it is possible that the thread-pool deadlocks waiting | ||
147 | for execution contexts to free up. | ||
148 | |||
149 | |||
150 | 4. Application Programming Interface (API) | ||
151 | |||
152 | alloc_workqueue() allocates a wq. The original create_*workqueue() | ||
153 | functions are deprecated and scheduled for removal. alloc_workqueue() | ||
154 | takes three arguments - @name, @flags and @max_active. @name is the | ||
155 | name of the wq and also used as the name of the rescuer thread if | ||
156 | there is one. | ||
157 | |||
158 | A wq no longer manages execution resources but serves as a domain for | ||
159 | forward progress guarantee, flush and work item attributes. @flags | ||
160 | and @max_active control how work items are assigned execution | ||
161 | resources, scheduled and executed. | ||
162 | |||
163 | @flags: | ||
164 | |||
165 | WQ_NON_REENTRANT | ||
166 | |||
167 | By default, a wq guarantees non-reentrance only on the same | ||
168 | CPU. A work item may not be executed concurrently on the same | ||
169 | CPU by multiple workers but is allowed to be executed | ||
170 | concurrently on multiple CPUs. This flag makes sure | ||
171 | non-reentrance is enforced across all CPUs. Work items queued | ||
172 | to a non-reentrant wq are guaranteed to be executed by at most | ||
173 | one worker system-wide at any given time. | ||
174 | |||
175 | WQ_UNBOUND | ||
176 | |||
177 | Work items queued to an unbound wq are served by a special | ||
178 | gcwq which hosts workers which are not bound to any specific | ||
179 | CPU. This makes the wq behave as a simple execution context | ||
180 | provider without concurrency management. The unbound gcwq | ||
181 | tries to start execution of work items as soon as possible. | ||
182 | Unbound wq sacrifices locality but is useful for the following | ||
183 | cases. | ||
184 | |||
185 | * Wide fluctuation in the concurrency level requirement is | ||
186 | expected and using bound wq may end up creating large number | ||
187 | of mostly unused workers across different CPUs as the issuer | ||
188 | hops through different CPUs. | ||
189 | |||
190 | * Long running CPU intensive workloads which can be better | ||
191 | managed by the system scheduler. | ||
192 | |||
193 | WQ_FREEZEABLE | ||
194 | |||
195 | A freezeable wq participates in the freeze phase of the system | ||
196 | suspend operations. Work items on the wq are drained and no | ||
197 | new work item starts execution until thawed. | ||
198 | |||
199 | WQ_RESCUER | ||
200 | |||
201 | All wq which might be used in the memory reclaim paths _MUST_ | ||
202 | have this flag set. This reserves one worker exclusively for | ||
203 | the execution of this wq under memory pressure. | ||
204 | |||
205 | WQ_HIGHPRI | ||
206 | |||
207 | Work items of a highpri wq are queued at the head of the | ||
208 | worklist of the target gcwq and start execution regardless of | ||
209 | the current concurrency level. In other words, highpri work | ||
210 | items will always start execution as soon as execution | ||
211 | resource is available. | ||
212 | |||
213 | Ordering among highpri work items is preserved - a highpri | ||
214 | work item queued after another highpri work item will start | ||
215 | execution after the earlier highpri work item starts. | ||
216 | |||
217 | Although highpri work items are not held back by other | ||
218 | runnable work items, they still contribute to the concurrency | ||
219 | level. Highpri work items in runnable state will prevent | ||
220 | non-highpri work items from starting execution. | ||
221 | |||
222 | This flag is meaningless for unbound wq. | ||
223 | |||
224 | WQ_CPU_INTENSIVE | ||
225 | |||
226 | Work items of a CPU intensive wq do not contribute to the | ||
227 | concurrency level. In other words, runnable CPU intensive | ||
228 | work items will not prevent other work items from starting | ||
229 | execution. This is useful for bound work items which are | ||
230 | expected to hog CPU cycles so that their execution is | ||
231 | regulated by the system scheduler. | ||
232 | |||
233 | Although CPU intensive work items don't contribute to the | ||
234 | concurrency level, start of their executions is still | ||
235 | regulated by the concurrency management and runnable | ||
236 | non-CPU-intensive work items can delay execution of CPU | ||
237 | intensive work items. | ||
238 | |||
239 | This flag is meaningless for unbound wq. | ||
240 | |||
241 | WQ_HIGHPRI | WQ_CPU_INTENSIVE | ||
242 | |||
243 | This combination makes the wq avoid interaction with | ||
244 | concurrency management completely and behave as a simple | ||
245 | per-CPU execution context provider. Work items queued on a | ||
246 | highpri CPU-intensive wq start execution as soon as resources | ||
247 | are available and don't affect execution of other work items. | ||
248 | |||
249 | @max_active: | ||
250 | |||
251 | @max_active determines the maximum number of execution contexts per | ||
252 | CPU which can be assigned to the work items of a wq. For example, | ||
253 | with @max_active of 16, at most 16 work items of the wq can be | ||
254 | executing at the same time per CPU. | ||
255 | |||
256 | Currently, for a bound wq, the maximum limit for @max_active is 512 | ||
257 | and the default value used when 0 is specified is 256. For an unbound | ||
258 | wq, the limit is higher of 512 and 4 * num_possible_cpus(). These | ||
259 | values are chosen sufficiently high such that they are not the | ||
260 | limiting factor while providing protection in runaway cases. | ||
261 | |||
262 | The number of active work items of a wq is usually regulated by the | ||
263 | users of the wq, more specifically, by how many work items the users | ||
264 | may queue at the same time. Unless there is a specific need for | ||
265 | throttling the number of active work items, specifying '0' is | ||
266 | recommended. | ||
267 | |||
268 | Some users depend on the strict execution ordering of ST wq. The | ||
269 | combination of @max_active of 1 and WQ_UNBOUND is used to achieve this | ||
270 | behavior. Work items on such wq are always queued to the unbound gcwq | ||
271 | and only one work item can be active at any given time thus achieving | ||
272 | the same ordering property as ST wq. | ||
273 | |||
274 | |||
275 | 5. Example Execution Scenarios | ||
276 | |||
277 | The following example execution scenarios try to illustrate how cmwq | ||
278 | behave under different configurations. | ||
279 | |||
280 | Work items w0, w1, w2 are queued to a bound wq q0 on the same CPU. | ||
281 | w0 burns CPU for 5ms then sleeps for 10ms then burns CPU for 5ms | ||
282 | again before finishing. w1 and w2 burn CPU for 5ms then sleep for | ||
283 | 10ms. | ||
284 | |||
285 | Ignoring all other tasks, works and processing overhead, and assuming | ||
286 | simple FIFO scheduling, the following is one highly simplified version | ||
287 | of possible sequences of events with the original wq. | ||
288 | |||
289 | TIME IN MSECS EVENT | ||
290 | 0 w0 starts and burns CPU | ||
291 | 5 w0 sleeps | ||
292 | 15 w0 wakes up and burns CPU | ||
293 | 20 w0 finishes | ||
294 | 20 w1 starts and burns CPU | ||
295 | 25 w1 sleeps | ||
296 | 35 w1 wakes up and finishes | ||
297 | 35 w2 starts and burns CPU | ||
298 | 40 w2 sleeps | ||
299 | 50 w2 wakes up and finishes | ||
300 | |||
301 | And with cmwq with @max_active >= 3, | ||
302 | |||
303 | TIME IN MSECS EVENT | ||
304 | 0 w0 starts and burns CPU | ||
305 | 5 w0 sleeps | ||
306 | 5 w1 starts and burns CPU | ||
307 | 10 w1 sleeps | ||
308 | 10 w2 starts and burns CPU | ||
309 | 15 w2 sleeps | ||
310 | 15 w0 wakes up and burns CPU | ||
311 | 20 w0 finishes | ||
312 | 20 w1 wakes up and finishes | ||
313 | 25 w2 wakes up and finishes | ||
314 | |||
315 | If @max_active == 2, | ||
316 | |||
317 | TIME IN MSECS EVENT | ||
318 | 0 w0 starts and burns CPU | ||
319 | 5 w0 sleeps | ||
320 | 5 w1 starts and burns CPU | ||
321 | 10 w1 sleeps | ||
322 | 15 w0 wakes up and burns CPU | ||
323 | 20 w0 finishes | ||
324 | 20 w1 wakes up and finishes | ||
325 | 20 w2 starts and burns CPU | ||
326 | 25 w2 sleeps | ||
327 | 35 w2 wakes up and finishes | ||
328 | |||
329 | Now, let's assume w1 and w2 are queued to a different wq q1 which has | ||
330 | WQ_HIGHPRI set, | ||
331 | |||
332 | TIME IN MSECS EVENT | ||
333 | 0 w1 and w2 start and burn CPU | ||
334 | 5 w1 sleeps | ||
335 | 10 w2 sleeps | ||
336 | 10 w0 starts and burns CPU | ||
337 | 15 w0 sleeps | ||
338 | 15 w1 wakes up and finishes | ||
339 | 20 w2 wakes up and finishes | ||
340 | 25 w0 wakes up and burns CPU | ||
341 | 30 w0 finishes | ||
342 | |||
343 | If q1 has WQ_CPU_INTENSIVE set, | ||
344 | |||
345 | TIME IN MSECS EVENT | ||
346 | 0 w0 starts and burns CPU | ||
347 | 5 w0 sleeps | ||
348 | 5 w1 and w2 start and burn CPU | ||
349 | 10 w1 sleeps | ||
350 | 15 w2 sleeps | ||
351 | 15 w0 wakes up and burns CPU | ||
352 | 20 w0 finishes | ||
353 | 20 w1 wakes up and finishes | ||
354 | 25 w2 wakes up and finishes | ||
355 | |||
356 | |||
357 | 6. Guidelines | ||
358 | |||
359 | * Do not forget to use WQ_RESCUER if a wq may process work items which | ||
360 | are used during memory reclaim. Each wq with WQ_RESCUER set has one | ||
361 | rescuer thread reserved for it. If there is dependency among | ||
362 | multiple work items used during memory reclaim, they should be | ||
363 | queued to separate wq each with WQ_RESCUER. | ||
364 | |||
365 | * Unless strict ordering is required, there is no need to use ST wq. | ||
366 | |||
367 | * Unless there is a specific need, using 0 for @max_active is | ||
368 | recommended. In most use cases, concurrency level usually stays | ||
369 | well under the default limit. | ||
370 | |||
371 | * A wq serves as a domain for forward progress guarantee (WQ_RESCUER), | ||
372 | flush and work item attributes. Work items which are not involved | ||
373 | in memory reclaim and don't need to be flushed as a part of a group | ||
374 | of work items, and don't require any special attribute, can use one | ||
375 | of the system wq. There is no difference in execution | ||
376 | characteristics between using a dedicated wq and a system wq. | ||
377 | |||
378 | * Unless work items are expected to consume a huge amount of CPU | ||
379 | cycles, using a bound wq is usually beneficial due to the increased | ||
380 | level of locality in wq operations and work item execution. | ||