aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio31
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt.xml4
-rw-r--r--Documentation/DocBook/media/v4l/v4l2.xml2
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-create-bufs.xml5
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-dqevent.xml2
-rw-r--r--Documentation/arm/SPEAr/overview.txt2
-rw-r--r--Documentation/device-mapper/verity.txt131
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-mux-pinctrl.txt93
-rw-r--r--Documentation/hwmon/coretemp22
-rw-r--r--Documentation/kernel-parameters.txt9
-rw-r--r--Documentation/networking/stmmac.txt44
-rw-r--r--Documentation/prctl/no_new_privs.txt50
-rw-r--r--Documentation/stable_kernel_rules.txt6
-rw-r--r--Documentation/vm/frontswap.txt278
14 files changed, 566 insertions, 113 deletions
diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
index 5bc8a476c15e..cfedf63cce15 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio
+++ b/Documentation/ABI/testing/sysfs-bus-iio
@@ -219,6 +219,7 @@ What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_scale
219What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_supply_scale 219What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_supply_scale
220What: /sys/bus/iio/devices/iio:deviceX/in_voltage_scale 220What: /sys/bus/iio/devices/iio:deviceX/in_voltage_scale
221What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_scale 221What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_scale
222What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_scale
222What: /sys/bus/iio/devices/iio:deviceX/in_accel_scale 223What: /sys/bus/iio/devices/iio:deviceX/in_accel_scale
223What: /sys/bus/iio/devices/iio:deviceX/in_accel_peak_scale 224What: /sys/bus/iio/devices/iio:deviceX/in_accel_peak_scale
224What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_scale 225What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_scale
@@ -273,6 +274,7 @@ What: /sys/bus/iio/devices/iio:deviceX/in_accel_scale_available
273What: /sys/.../iio:deviceX/in_voltageX_scale_available 274What: /sys/.../iio:deviceX/in_voltageX_scale_available
274What: /sys/.../iio:deviceX/in_voltage-voltage_scale_available 275What: /sys/.../iio:deviceX/in_voltage-voltage_scale_available
275What: /sys/.../iio:deviceX/out_voltageX_scale_available 276What: /sys/.../iio:deviceX/out_voltageX_scale_available
277What: /sys/.../iio:deviceX/out_altvoltageX_scale_available
276What: /sys/.../iio:deviceX/in_capacitance_scale_available 278What: /sys/.../iio:deviceX/in_capacitance_scale_available
277KernelVersion: 2.635 279KernelVersion: 2.635
278Contact: linux-iio@vger.kernel.org 280Contact: linux-iio@vger.kernel.org
@@ -298,14 +300,19 @@ Description:
298 gives the 3dB frequency of the filter in Hz. 300 gives the 3dB frequency of the filter in Hz.
299 301
300What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_raw 302What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_raw
303What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_raw
301KernelVersion: 2.6.37 304KernelVersion: 2.6.37
302Contact: linux-iio@vger.kernel.org 305Contact: linux-iio@vger.kernel.org
303Description: 306Description:
304 Raw (unscaled, no bias etc.) output voltage for 307 Raw (unscaled, no bias etc.) output voltage for
305 channel Y. The number must always be specified and 308 channel Y. The number must always be specified and
306 unique if the output corresponds to a single channel. 309 unique if the output corresponds to a single channel.
310 While DAC like devices typically use out_voltage,
311 a continuous frequency generating device, such as
312 a DDS or PLL should use out_altvoltage.
307 313
308What: /sys/bus/iio/devices/iio:deviceX/out_voltageY&Z_raw 314What: /sys/bus/iio/devices/iio:deviceX/out_voltageY&Z_raw
315What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY&Z_raw
309KernelVersion: 2.6.37 316KernelVersion: 2.6.37
310Contact: linux-iio@vger.kernel.org 317Contact: linux-iio@vger.kernel.org
311Description: 318Description:
@@ -316,6 +323,8 @@ Description:
316 323
317What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_powerdown_mode 324What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_powerdown_mode
318What: /sys/bus/iio/devices/iio:deviceX/out_voltage_powerdown_mode 325What: /sys/bus/iio/devices/iio:deviceX/out_voltage_powerdown_mode
326What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_powerdown_mode
327What: /sys/bus/iio/devices/iio:deviceX/out_altvoltage_powerdown_mode
319KernelVersion: 2.6.38 328KernelVersion: 2.6.38
320Contact: linux-iio@vger.kernel.org 329Contact: linux-iio@vger.kernel.org
321Description: 330Description:
@@ -330,6 +339,8 @@ Description:
330 339
331What: /sys/.../iio:deviceX/out_votlageY_powerdown_mode_available 340What: /sys/.../iio:deviceX/out_votlageY_powerdown_mode_available
332What: /sys/.../iio:deviceX/out_voltage_powerdown_mode_available 341What: /sys/.../iio:deviceX/out_voltage_powerdown_mode_available
342What: /sys/.../iio:deviceX/out_altvotlageY_powerdown_mode_available
343What: /sys/.../iio:deviceX/out_altvoltage_powerdown_mode_available
333KernelVersion: 2.6.38 344KernelVersion: 2.6.38
334Contact: linux-iio@vger.kernel.org 345Contact: linux-iio@vger.kernel.org
335Description: 346Description:
@@ -338,6 +349,8 @@ Description:
338 349
339What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_powerdown 350What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_powerdown
340What: /sys/bus/iio/devices/iio:deviceX/out_voltage_powerdown 351What: /sys/bus/iio/devices/iio:deviceX/out_voltage_powerdown
352What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_powerdown
353What: /sys/bus/iio/devices/iio:deviceX/out_altvoltage_powerdown
341KernelVersion: 2.6.38 354KernelVersion: 2.6.38
342Contact: linux-iio@vger.kernel.org 355Contact: linux-iio@vger.kernel.org
343Description: 356Description:
@@ -346,6 +359,24 @@ Description:
346 normal operation. Y may be suppressed if all outputs are 359 normal operation. Y may be suppressed if all outputs are
347 controlled together. 360 controlled together.
348 361
362What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_frequency
363KernelVersion: 3.4.0
364Contact: linux-iio@vger.kernel.org
365Description:
366 Output frequency for channel Y in Hz. The number must always be
367 specified and unique if the output corresponds to a single
368 channel.
369
370What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_phase
371KernelVersion: 3.4.0
372Contact: linux-iio@vger.kernel.org
373Description:
374 Phase in radians of one frequency/clock output Y
375 (out_altvoltageY) relative to another frequency/clock output
376 (out_altvoltageZ) of the device X. The number must always be
377 specified and unique if the output corresponds to a single
378 channel.
379
349What: /sys/bus/iio/devices/iio:deviceX/events 380What: /sys/bus/iio/devices/iio:deviceX/events
350KernelVersion: 2.6.35 381KernelVersion: 2.6.35
351Contact: linux-iio@vger.kernel.org 382Contact: linux-iio@vger.kernel.org
diff --git a/Documentation/DocBook/media/v4l/pixfmt.xml b/Documentation/DocBook/media/v4l/pixfmt.xml
index f5ac15ed0549..e58934c92895 100644
--- a/Documentation/DocBook/media/v4l/pixfmt.xml
+++ b/Documentation/DocBook/media/v4l/pixfmt.xml
@@ -986,13 +986,13 @@ http://www.thedirks.org/winnov/</ulink></para></entry>
986 <row id="V4L2-PIX-FMT-Y4"> 986 <row id="V4L2-PIX-FMT-Y4">
987 <entry><constant>V4L2_PIX_FMT_Y4</constant></entry> 987 <entry><constant>V4L2_PIX_FMT_Y4</constant></entry>
988 <entry>'Y04 '</entry> 988 <entry>'Y04 '</entry>
989 <entry>Old 4-bit greyscale format. Only the least significant 4 bits of each byte are used, 989 <entry>Old 4-bit greyscale format. Only the most significant 4 bits of each byte are used,
990the other bits are set to 0.</entry> 990the other bits are set to 0.</entry>
991 </row> 991 </row>
992 <row id="V4L2-PIX-FMT-Y6"> 992 <row id="V4L2-PIX-FMT-Y6">
993 <entry><constant>V4L2_PIX_FMT_Y6</constant></entry> 993 <entry><constant>V4L2_PIX_FMT_Y6</constant></entry>
994 <entry>'Y06 '</entry> 994 <entry>'Y06 '</entry>
995 <entry>Old 6-bit greyscale format. Only the least significant 6 bits of each byte are used, 995 <entry>Old 6-bit greyscale format. Only the most significant 6 bits of each byte are used,
996the other bits are set to 0.</entry> 996the other bits are set to 0.</entry>
997 </row> 997 </row>
998 </tbody> 998 </tbody>
diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml
index 015c561754b7..008c2d73a484 100644
--- a/Documentation/DocBook/media/v4l/v4l2.xml
+++ b/Documentation/DocBook/media/v4l/v4l2.xml
@@ -560,6 +560,7 @@ and discussions on the V4L mailing list.</revremark>
560 &sub-g-tuner; 560 &sub-g-tuner;
561 &sub-log-status; 561 &sub-log-status;
562 &sub-overlay; 562 &sub-overlay;
563 &sub-prepare-buf;
563 &sub-qbuf; 564 &sub-qbuf;
564 &sub-querybuf; 565 &sub-querybuf;
565 &sub-querycap; 566 &sub-querycap;
@@ -567,7 +568,6 @@ and discussions on the V4L mailing list.</revremark>
567 &sub-query-dv-preset; 568 &sub-query-dv-preset;
568 &sub-query-dv-timings; 569 &sub-query-dv-timings;
569 &sub-querystd; 570 &sub-querystd;
570 &sub-prepare-buf;
571 &sub-reqbufs; 571 &sub-reqbufs;
572 &sub-s-hw-freq-seek; 572 &sub-s-hw-freq-seek;
573 &sub-streamon; 573 &sub-streamon;
diff --git a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml
index 765549ff8a71..a2474ecb574a 100644
--- a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml
@@ -108,10 +108,9 @@ information.</para>
108/></entry> 108/></entry>
109 </row> 109 </row>
110 <row> 110 <row>
111 <entry>__u32</entry> 111 <entry>struct&nbsp;v4l2_format</entry>
112 <entry><structfield>format</structfield></entry> 112 <entry><structfield>format</structfield></entry>
113 <entry>Filled in by the application, preserved by the driver. 113 <entry>Filled in by the application, preserved by the driver.</entry>
114 See <xref linkend="v4l2-format" />.</entry>
115 </row> 114 </row>
116 <row> 115 <row>
117 <entry>__u32</entry> 116 <entry>__u32</entry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-dqevent.xml b/Documentation/DocBook/media/v4l/vidioc-dqevent.xml
index e8714aa16433..98a856f9ec30 100644
--- a/Documentation/DocBook/media/v4l/vidioc-dqevent.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-dqevent.xml
@@ -89,7 +89,7 @@
89 <row> 89 <row>
90 <entry></entry> 90 <entry></entry>
91 <entry>&v4l2-event-frame-sync;</entry> 91 <entry>&v4l2-event-frame-sync;</entry>
92 <entry><structfield>frame</structfield></entry> 92 <entry><structfield>frame_sync</structfield></entry>
93 <entry>Event data for event V4L2_EVENT_FRAME_SYNC.</entry> 93 <entry>Event data for event V4L2_EVENT_FRAME_SYNC.</entry>
94 </row> 94 </row>
95 <row> 95 <row>
diff --git a/Documentation/arm/SPEAr/overview.txt b/Documentation/arm/SPEAr/overview.txt
index 57aae7765c74..65610bf52ebf 100644
--- a/Documentation/arm/SPEAr/overview.txt
+++ b/Documentation/arm/SPEAr/overview.txt
@@ -60,4 +60,4 @@ Introduction
60 Document Author 60 Document Author
61 --------------- 61 ---------------
62 62
63 Viresh Kumar <viresh.kumar@st.com>, (c) 2010-2012 ST Microelectronics 63 Viresh Kumar <viresh.linux@gmail.com>, (c) 2010-2012 ST Microelectronics
diff --git a/Documentation/device-mapper/verity.txt b/Documentation/device-mapper/verity.txt
index 32e48797a14f..9884681535ee 100644
--- a/Documentation/device-mapper/verity.txt
+++ b/Documentation/device-mapper/verity.txt
@@ -7,39 +7,39 @@ This target is read-only.
7 7
8Construction Parameters 8Construction Parameters
9======================= 9=======================
10 <version> <dev> <hash_dev> <hash_start> 10 <version> <dev> <hash_dev>
11 <data_block_size> <hash_block_size> 11 <data_block_size> <hash_block_size>
12 <num_data_blocks> <hash_start_block> 12 <num_data_blocks> <hash_start_block>
13 <algorithm> <digest> <salt> 13 <algorithm> <digest> <salt>
14 14
15<version> 15<version>
16 This is the version number of the on-disk format. 16 This is the type of the on-disk hash format.
17 17
18 0 is the original format used in the Chromium OS. 18 0 is the original format used in the Chromium OS.
19 The salt is appended when hashing, digests are stored continuously and 19 The salt is appended when hashing, digests are stored continuously and
20 the rest of the block is padded with zeros. 20 the rest of the block is padded with zeros.
21 21
22 1 is the current format that should be used for new devices. 22 1 is the current format that should be used for new devices.
23 The salt is prepended when hashing and each digest is 23 The salt is prepended when hashing and each digest is
24 padded with zeros to the power of two. 24 padded with zeros to the power of two.
25 25
26<dev> 26<dev>
27 This is the device containing the data the integrity of which needs to be 27 This is the device containing data, the integrity of which needs to be
28 checked. It may be specified as a path, like /dev/sdaX, or a device number, 28 checked. It may be specified as a path, like /dev/sdaX, or a device number,
29 <major>:<minor>. 29 <major>:<minor>.
30 30
31<hash_dev> 31<hash_dev>
32 This is the device that that supplies the hash tree data. It may be 32 This is the device that supplies the hash tree data. It may be
33 specified similarly to the device path and may be the same device. If the 33 specified similarly to the device path and may be the same device. If the
34 same device is used, the hash_start should be outside of the dm-verity 34 same device is used, the hash_start should be outside the configured
35 configured device size. 35 dm-verity device.
36 36
37<data_block_size> 37<data_block_size>
38 The block size on a data device. Each block corresponds to one digest on 38 The block size on a data device in bytes.
39 the hash device. 39 Each block corresponds to one digest on the hash device.
40 40
41<hash_block_size> 41<hash_block_size>
42 The size of a hash block. 42 The size of a hash block in bytes.
43 43
44<num_data_blocks> 44<num_data_blocks>
45 The number of data blocks on the data device. Additional blocks are 45 The number of data blocks on the data device. Additional blocks are
@@ -65,7 +65,7 @@ Construction Parameters
65Theory of operation 65Theory of operation
66=================== 66===================
67 67
68dm-verity is meant to be setup as part of a verified boot path. This 68dm-verity is meant to be set up as part of a verified boot path. This
69may be anything ranging from a boot using tboot or trustedgrub to just 69may be anything ranging from a boot using tboot or trustedgrub to just
70booting from a known-good device (like a USB drive or CD). 70booting from a known-good device (like a USB drive or CD).
71 71
@@ -73,20 +73,20 @@ When a dm-verity device is configured, it is expected that the caller
73has been authenticated in some way (cryptographic signatures, etc). 73has been authenticated in some way (cryptographic signatures, etc).
74After instantiation, all hashes will be verified on-demand during 74After instantiation, all hashes will be verified on-demand during
75disk access. If they cannot be verified up to the root node of the 75disk access. If they cannot be verified up to the root node of the
76tree, the root hash, then the I/O will fail. This should identify 76tree, the root hash, then the I/O will fail. This should detect
77tampering with any data on the device and the hash data. 77tampering with any data on the device and the hash data.
78 78
79Cryptographic hashes are used to assert the integrity of the device on a 79Cryptographic hashes are used to assert the integrity of the device on a
80per-block basis. This allows for a lightweight hash computation on first read 80per-block basis. This allows for a lightweight hash computation on first read
81into the page cache. Block hashes are stored linearly-aligned to the nearest 81into the page cache. Block hashes are stored linearly, aligned to the nearest
82block the size of a page. 82block size.
83 83
84Hash Tree 84Hash Tree
85--------- 85---------
86 86
87Each node in the tree is a cryptographic hash. If it is a leaf node, the hash 87Each node in the tree is a cryptographic hash. If it is a leaf node, the hash
88is of some block data on disk. If it is an intermediary node, then the hash is 88of some data block on disk is calculated. If it is an intermediary node,
89of a number of child nodes. 89the hash of a number of child nodes is calculated.
90 90
91Each entry in the tree is a collection of neighboring nodes that fit in one 91Each entry in the tree is a collection of neighboring nodes that fit in one
92block. The number is determined based on block_size and the size of the 92block. The number is determined based on block_size and the size of the
@@ -110,63 +110,23 @@ alg = sha256, num_blocks = 32768, block_size = 4096
110On-disk format 110On-disk format
111============== 111==============
112 112
113Below is the recommended on-disk format. The verity kernel code does not 113The verity kernel code does not read the verity metadata on-disk header.
114read the on-disk header. It only reads the hash blocks which directly 114It only reads the hash blocks which directly follow the header.
115follow the header. It is expected that a user-space tool will verify the 115It is expected that a user-space tool will verify the integrity of the
116integrity of the verity_header and then call dmsetup with the correct 116verity header.
117parameters. Alternatively, the header can be omitted and the dmsetup
118parameters can be passed via the kernel command-line in a rooted chain
119of trust where the command-line is verified.
120 117
121The on-disk format is especially useful in cases where the hash blocks 118Alternatively, the header can be omitted and the dmsetup parameters can
122are on a separate partition. The magic number allows easy identification 119be passed via the kernel command-line in a rooted chain of trust where
123of the partition contents. Alternatively, the hash blocks can be stored 120the command-line is verified.
124in the same partition as the data to be verified. In such a configuration
125the filesystem on the partition would be sized a little smaller than
126the full-partition, leaving room for the hash blocks.
127
128struct superblock {
129 uint8_t signature[8]
130 "verity\0\0";
131
132 uint8_t version;
133 1 - current format
134
135 uint8_t data_block_bits;
136 log2(data block size)
137
138 uint8_t hash_block_bits;
139 log2(hash block size)
140
141 uint8_t pad1[1];
142 zero padding
143
144 uint16_t salt_size;
145 big-endian salt size
146
147 uint8_t pad2[2];
148 zero padding
149
150 uint32_t data_blocks_hi;
151 big-endian high 32 bits of the 64-bit number of data blocks
152
153 uint32_t data_blocks_lo;
154 big-endian low 32 bits of the 64-bit number of data blocks
155
156 uint8_t algorithm[16];
157 cryptographic algorithm
158
159 uint8_t salt[384];
160 salt (the salt size is specified above)
161
162 uint8_t pad3[88];
163 zero padding to 512-byte boundary
164}
165 121
166Directly following the header (and with sector number padded to the next hash 122Directly following the header (and with sector number padded to the next hash
167block boundary) are the hash blocks which are stored a depth at a time 123block boundary) are the hash blocks which are stored a depth at a time
168(starting from the root), sorted in order of increasing index. 124(starting from the root), sorted in order of increasing index.
169 125
126The full specification of kernel parameters and on-disk metadata format
127is available at the cryptsetup project's wiki page
128 http://code.google.com/p/cryptsetup/wiki/DMVerity
129
170Status 130Status
171====== 131======
172V (for Valid) is returned if every check performed so far was valid. 132V (for Valid) is returned if every check performed so far was valid.
@@ -174,21 +134,22 @@ If any check failed, C (for Corruption) is returned.
174 134
175Example 135Example
176======= 136=======
177 137Set up a device:
178Setup a device: 138 # dmsetup create vroot --readonly --table \
179 dmsetup create vroot --table \ 139 "0 2097152 verity 1 /dev/sda1 /dev/sda2 4096 4096 262144 1 sha256 "\
180 "0 2097152 "\
181 "verity 1 /dev/sda1 /dev/sda2 4096 4096 2097152 1 "\
182 "4392712ba01368efdf14b05c76f9e4df0d53664630b5d48632ed17a137f39076 "\ 140 "4392712ba01368efdf14b05c76f9e4df0d53664630b5d48632ed17a137f39076 "\
183 "1234000000000000000000000000000000000000000000000000000000000000" 141 "1234000000000000000000000000000000000000000000000000000000000000"
184 142
185A command line tool veritysetup is available to compute or verify 143A command line tool veritysetup is available to compute or verify
186the hash tree or activate the kernel driver. This is available from 144the hash tree or activate the kernel device. This is available from
187the LVM2 upstream repository and may be supplied as a package called 145the cryptsetup upstream repository http://code.google.com/p/cryptsetup/
188device-mapper-verity-tools: 146(as a libcryptsetup extension).
189 git://sources.redhat.com/git/lvm2 147
190 http://sourceware.org/git/?p=lvm2.git 148Create hash on the device:
191 http://sourceware.org/cgi-bin/cvsweb.cgi/LVM2/verity?cvsroot=lvm2 149 # veritysetup format /dev/sda1 /dev/sda2
192 150 ...
193veritysetup -a vroot /dev/sda1 /dev/sda2 \ 151 Root hash: 4392712ba01368efdf14b05c76f9e4df0d53664630b5d48632ed17a137f39076
194 4392712ba01368efdf14b05c76f9e4df0d53664630b5d48632ed17a137f39076 152
153Activate the device:
154 # veritysetup create vroot /dev/sda1 /dev/sda2 \
155 4392712ba01368efdf14b05c76f9e4df0d53664630b5d48632ed17a137f39076
diff --git a/Documentation/devicetree/bindings/i2c/i2c-mux-pinctrl.txt b/Documentation/devicetree/bindings/i2c/i2c-mux-pinctrl.txt
new file mode 100644
index 000000000000..ae8af1694e95
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/i2c-mux-pinctrl.txt
@@ -0,0 +1,93 @@
1Pinctrl-based I2C Bus Mux
2
3This binding describes an I2C bus multiplexer that uses pin multiplexing to
4route the I2C signals, and represents the pin multiplexing configuration
5using the pinctrl device tree bindings.
6
7 +-----+ +-----+
8 | dev | | dev |
9 +------------------------+ +-----+ +-----+
10 | SoC | | |
11 | /----|------+--------+
12 | +---+ +------+ | child bus A, on first set of pins
13 | |I2C|---|Pinmux| |
14 | +---+ +------+ | child bus B, on second set of pins
15 | \----|------+--------+--------+
16 | | | | |
17 +------------------------+ +-----+ +-----+ +-----+
18 | dev | | dev | | dev |
19 +-----+ +-----+ +-----+
20
21Required properties:
22- compatible: i2c-mux-pinctrl
23- i2c-parent: The phandle of the I2C bus that this multiplexer's master-side
24 port is connected to.
25
26Also required are:
27
28* Standard pinctrl properties that specify the pin mux state for each child
29 bus. See ../pinctrl/pinctrl-bindings.txt.
30
31* Standard I2C mux properties. See mux.txt in this directory.
32
33* I2C child bus nodes. See mux.txt in this directory.
34
35For each named state defined in the pinctrl-names property, an I2C child bus
36will be created. I2C child bus numbers are assigned based on the index into
37the pinctrl-names property.
38
39The only exception is that no bus will be created for a state named "idle". If
40such a state is defined, it must be the last entry in pinctrl-names. For
41example:
42
43 pinctrl-names = "ddc", "pta", "idle" -> ddc = bus 0, pta = bus 1
44 pinctrl-names = "ddc", "idle", "pta" -> Invalid ("idle" not last)
45 pinctrl-names = "idle", "ddc", "pta" -> Invalid ("idle" not last)
46
47Whenever an access is made to a device on a child bus, the relevant pinctrl
48state will be programmed into hardware.
49
50If an idle state is defined, whenever an access is not being made to a device
51on a child bus, the idle pinctrl state will be programmed into hardware.
52
53If an idle state is not defined, the most recently used pinctrl state will be
54left programmed into hardware whenever no access is being made of a device on
55a child bus.
56
57Example:
58
59 i2cmux {
60 compatible = "i2c-mux-pinctrl";
61 #address-cells = <1>;
62 #size-cells = <0>;
63
64 i2c-parent = <&i2c1>;
65
66 pinctrl-names = "ddc", "pta", "idle";
67 pinctrl-0 = <&state_i2cmux_ddc>;
68 pinctrl-1 = <&state_i2cmux_pta>;
69 pinctrl-2 = <&state_i2cmux_idle>;
70
71 i2c@0 {
72 reg = <0>;
73 #address-cells = <1>;
74 #size-cells = <0>;
75
76 eeprom {
77 compatible = "eeprom";
78 reg = <0x50>;
79 };
80 };
81
82 i2c@1 {
83 reg = <1>;
84 #address-cells = <1>;
85 #size-cells = <0>;
86
87 eeprom {
88 compatible = "eeprom";
89 reg = <0x50>;
90 };
91 };
92 };
93
diff --git a/Documentation/hwmon/coretemp b/Documentation/hwmon/coretemp
index 84d46c0c71a3..c86b50c03ea8 100644
--- a/Documentation/hwmon/coretemp
+++ b/Documentation/hwmon/coretemp
@@ -6,7 +6,9 @@ Supported chips:
6 Prefix: 'coretemp' 6 Prefix: 'coretemp'
7 CPUID: family 0x6, models 0xe (Pentium M DC), 0xf (Core 2 DC 65nm), 7 CPUID: family 0x6, models 0xe (Pentium M DC), 0xf (Core 2 DC 65nm),
8 0x16 (Core 2 SC 65nm), 0x17 (Penryn 45nm), 8 0x16 (Core 2 SC 65nm), 0x17 (Penryn 45nm),
9 0x1a (Nehalem), 0x1c (Atom), 0x1e (Lynnfield) 9 0x1a (Nehalem), 0x1c (Atom), 0x1e (Lynnfield),
10 0x26 (Tunnel Creek Atom), 0x27 (Medfield Atom),
11 0x36 (Cedar Trail Atom)
10 Datasheet: Intel 64 and IA-32 Architectures Software Developer's Manual 12 Datasheet: Intel 64 and IA-32 Architectures Software Developer's Manual
11 Volume 3A: System Programming Guide 13 Volume 3A: System Programming Guide
12 http://softwarecommunity.intel.com/Wiki/Mobility/720.htm 14 http://softwarecommunity.intel.com/Wiki/Mobility/720.htm
@@ -52,6 +54,17 @@ Some information comes from ark.intel.com
52 54
53Process Processor TjMax(C) 55Process Processor TjMax(C)
54 56
5722nm Core i5/i7 Processors
58 i7 3920XM, 3820QM, 3720QM, 3667U, 3520M 105
59 i5 3427U, 3360M/3320M 105
60 i7 3770/3770K 105
61 i5 3570/3570K, 3550, 3470/3450 105
62 i7 3770S 103
63 i5 3570S/3550S, 3475S/3470S/3450S 103
64 i7 3770T 94
65 i5 3570T 94
66 i5 3470T 91
67
5532nm Core i3/i5/i7 Processors 6832nm Core i3/i5/i7 Processors
56 i7 660UM/640/620, 640LM/620, 620M, 610E 105 69 i7 660UM/640/620, 640LM/620, 620M, 610E 105
57 i5 540UM/520/430, 540M/520/450/430 105 70 i5 540UM/520/430, 540M/520/450/430 105
@@ -65,6 +78,11 @@ Process Processor TjMax(C)
65 U3400 105 78 U3400 105
66 P4505/P4500 90 79 P4505/P4500 90
67 80
8132nm Atom Processors
82 Z2460 90
83 D2700/2550/2500 100
84 N2850/2800/2650/2600 100
85
6845nm Xeon Processors 5400 Quad-Core 8645nm Xeon Processors 5400 Quad-Core
69 X5492, X5482, X5472, X5470, X5460, X5450 85 87 X5492, X5482, X5472, X5470, X5460, X5450 85
70 E5472, E5462, E5450/40/30/20/10/05 85 88 E5472, E5462, E5450/40/30/20/10/05 85
@@ -85,6 +103,8 @@ Process Processor TjMax(C)
85 N475/470/455/450 100 103 N475/470/455/450 100
86 N280/270 90 104 N280/270 90
87 330/230 125 105 330/230 125
106 E680/660/640/620 90
107 E680T/660T/640T/620T 110
88 108
8945nm Core2 Processors 10945nm Core2 Processors
90 Solo ULV SU3500/3300 100 110 Solo ULV SU3500/3300 100
diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt
index c45513d806ab..a92c5ebf373e 100644
--- a/Documentation/kernel-parameters.txt
+++ b/Documentation/kernel-parameters.txt
@@ -2543,6 +2543,15 @@ bytes respectively. Such letter suffixes can also be entirely omitted.
2543 2543
2544 sched_debug [KNL] Enables verbose scheduler debug messages. 2544 sched_debug [KNL] Enables verbose scheduler debug messages.
2545 2545
2546 skew_tick= [KNL] Offset the periodic timer tick per cpu to mitigate
2547 xtime_lock contention on larger systems, and/or RCU lock
2548 contention on all systems with CONFIG_MAXSMP set.
2549 Format: { "0" | "1" }
2550 0 -- disable. (may be 1 via CONFIG_CMDLINE="skew_tick=1"
2551 1 -- enable.
2552 Note: increases power consumption, thus should only be
2553 enabled if running jitter sensitive (HPC/RT) workloads.
2554
2546 security= [SECURITY] Choose a security module to enable at boot. 2555 security= [SECURITY] Choose a security module to enable at boot.
2547 If this boot parameter is not specified, only the first 2556 If this boot parameter is not specified, only the first
2548 security module asking for security registration will be 2557 security module asking for security registration will be
diff --git a/Documentation/networking/stmmac.txt b/Documentation/networking/stmmac.txt
index ab1e8d7004c5..5cb9a1972460 100644
--- a/Documentation/networking/stmmac.txt
+++ b/Documentation/networking/stmmac.txt
@@ -10,8 +10,8 @@ Currently this network device driver is for all STM embedded MAC/GMAC
10(i.e. 7xxx/5xxx SoCs), SPEAr (arm), Loongson1B (mips) and XLINX XC2V3000 10(i.e. 7xxx/5xxx SoCs), SPEAr (arm), Loongson1B (mips) and XLINX XC2V3000
11FF1152AMT0221 D1215994A VIRTEX FPGA board. 11FF1152AMT0221 D1215994A VIRTEX FPGA board.
12 12
13DWC Ether MAC 10/100/1000 Universal version 3.60a (and older) and DWC Ether MAC 10/100 13DWC Ether MAC 10/100/1000 Universal version 3.60a (and older) and DWC Ether
14Universal version 4.0 have been used for developing this driver. 14MAC 10/100 Universal version 4.0 have been used for developing this driver.
15 15
16This driver supports both the platform bus and PCI. 16This driver supports both the platform bus and PCI.
17 17
@@ -54,27 +54,27 @@ net_device structure enabling the scatter/gather feature.
54When one or more packets are received, an interrupt happens. The interrupts 54When one or more packets are received, an interrupt happens. The interrupts
55are not queued so the driver has to scan all the descriptors in the ring during 55are not queued so the driver has to scan all the descriptors in the ring during
56the receive process. 56the receive process.
57This is based on NAPI so the interrupt handler signals only if there is work to be 57This is based on NAPI so the interrupt handler signals only if there is work
58done, and it exits. 58to be done, and it exits.
59Then the poll method will be scheduled at some future point. 59Then the poll method will be scheduled at some future point.
60The incoming packets are stored, by the DMA, in a list of pre-allocated socket 60The incoming packets are stored, by the DMA, in a list of pre-allocated socket
61buffers in order to avoid the memcpy (Zero-copy). 61buffers in order to avoid the memcpy (Zero-copy).
62 62
634.3) Timer-Driver Interrupt 634.3) Timer-Driver Interrupt
64Instead of having the device that asynchronously notifies the frame receptions, the 64Instead of having the device that asynchronously notifies the frame receptions,
65driver configures a timer to generate an interrupt at regular intervals. 65the driver configures a timer to generate an interrupt at regular intervals.
66Based on the granularity of the timer, the frames that are received by the device 66Based on the granularity of the timer, the frames that are received by the
67will experience different levels of latency. Some NICs have dedicated timer 67device will experience different levels of latency. Some NICs have dedicated
68device to perform this task. STMMAC can use either the RTC device or the TMU 68timer device to perform this task. STMMAC can use either the RTC device or the
69channel 2 on STLinux platforms. 69TMU channel 2 on STLinux platforms.
70The timers frequency can be passed to the driver as parameter; when change it, 70The timers frequency can be passed to the driver as parameter; when change it,
71take care of both hardware capability and network stability/performance impact. 71take care of both hardware capability and network stability/performance impact.
72Several performance tests on STM platforms showed this optimisation allows to spare 72Several performance tests on STM platforms showed this optimisation allows to
73the CPU while having the maximum throughput. 73spare the CPU while having the maximum throughput.
74 74
754.4) WOL 754.4) WOL
76Wake up on Lan feature through Magic and Unicast frames are supported for the GMAC 76Wake up on Lan feature through Magic and Unicast frames are supported for the
77core. 77GMAC core.
78 78
794.5) DMA descriptors 794.5) DMA descriptors
80Driver handles both normal and enhanced descriptors. The latter has been only 80Driver handles both normal and enhanced descriptors. The latter has been only
@@ -106,7 +106,8 @@ Several driver's information can be passed through the platform
106These are included in the include/linux/stmmac.h header file 106These are included in the include/linux/stmmac.h header file
107and detailed below as well: 107and detailed below as well:
108 108
109 struct plat_stmmacenet_data { 109struct plat_stmmacenet_data {
110 char *phy_bus_name;
110 int bus_id; 111 int bus_id;
111 int phy_addr; 112 int phy_addr;
112 int interface; 113 int interface;
@@ -124,19 +125,24 @@ and detailed below as well:
124 void (*bus_setup)(void __iomem *ioaddr); 125 void (*bus_setup)(void __iomem *ioaddr);
125 int (*init)(struct platform_device *pdev); 126 int (*init)(struct platform_device *pdev);
126 void (*exit)(struct platform_device *pdev); 127 void (*exit)(struct platform_device *pdev);
128 void *custom_cfg;
129 void *custom_data;
127 void *bsp_priv; 130 void *bsp_priv;
128 }; 131 };
129 132
130Where: 133Where:
134 o phy_bus_name: phy bus name to attach to the stmmac.
131 o bus_id: bus identifier. 135 o bus_id: bus identifier.
132 o phy_addr: the physical address can be passed from the platform. 136 o phy_addr: the physical address can be passed from the platform.
133 If it is set to -1 the driver will automatically 137 If it is set to -1 the driver will automatically
134 detect it at run-time by probing all the 32 addresses. 138 detect it at run-time by probing all the 32 addresses.
135 o interface: PHY device's interface. 139 o interface: PHY device's interface.
136 o mdio_bus_data: specific platform fields for the MDIO bus. 140 o mdio_bus_data: specific platform fields for the MDIO bus.
137 o pbl: the Programmable Burst Length is maximum number of beats to 141 o dma_cfg: internal DMA parameters
142 o pbl: the Programmable Burst Length is maximum number of beats to
138 be transferred in one DMA transaction. 143 be transferred in one DMA transaction.
139 GMAC also enables the 4xPBL by default. 144 GMAC also enables the 4xPBL by default.
145 o fixed_burst/mixed_burst/burst_len
140 o clk_csr: fixed CSR Clock range selection. 146 o clk_csr: fixed CSR Clock range selection.
141 o has_gmac: uses the GMAC core. 147 o has_gmac: uses the GMAC core.
142 o enh_desc: if sets the MAC will use the enhanced descriptor structure. 148 o enh_desc: if sets the MAC will use the enhanced descriptor structure.
@@ -160,8 +166,9 @@ Where:
160 this is sometime necessary on some platforms (e.g. ST boxes) 166 this is sometime necessary on some platforms (e.g. ST boxes)
161 where the HW needs to have set some PIO lines or system cfg 167 where the HW needs to have set some PIO lines or system cfg
162 registers. 168 registers.
163 o custom_cfg: this is a custom configuration that can be passed while 169 o custom_cfg/custom_data: this is a custom configuration that can be passed
164 initialising the resources. 170 while initialising the resources.
171 o bsp_priv: another private poiter.
165 172
166For MDIO bus The we have: 173For MDIO bus The we have:
167 174
@@ -180,7 +187,6 @@ Where:
180 o irqs: list of IRQs, one per PHY. 187 o irqs: list of IRQs, one per PHY.
181 o probed_phy_irq: if irqs is NULL, use this for probed PHY. 188 o probed_phy_irq: if irqs is NULL, use this for probed PHY.
182 189
183
184For DMA engine we have the following internal fields that should be 190For DMA engine we have the following internal fields that should be
185tuned according to the HW capabilities. 191tuned according to the HW capabilities.
186 192
diff --git a/Documentation/prctl/no_new_privs.txt b/Documentation/prctl/no_new_privs.txt
new file mode 100644
index 000000000000..cb705ec69abe
--- /dev/null
+++ b/Documentation/prctl/no_new_privs.txt
@@ -0,0 +1,50 @@
1The execve system call can grant a newly-started program privileges that
2its parent did not have. The most obvious examples are setuid/setgid
3programs and file capabilities. To prevent the parent program from
4gaining these privileges as well, the kernel and user code must be
5careful to prevent the parent from doing anything that could subvert the
6child. For example:
7
8 - The dynamic loader handles LD_* environment variables differently if
9 a program is setuid.
10
11 - chroot is disallowed to unprivileged processes, since it would allow
12 /etc/passwd to be replaced from the point of view of a process that
13 inherited chroot.
14
15 - The exec code has special handling for ptrace.
16
17These are all ad-hoc fixes. The no_new_privs bit (since Linux 3.5) is a
18new, generic mechanism to make it safe for a process to modify its
19execution environment in a manner that persists across execve. Any task
20can set no_new_privs. Once the bit is set, it is inherited across fork,
21clone, and execve and cannot be unset. With no_new_privs set, execve
22promises not to grant the privilege to do anything that could not have
23been done without the execve call. For example, the setuid and setgid
24bits will no longer change the uid or gid; file capabilities will not
25add to the permitted set, and LSMs will not relax constraints after
26execve.
27
28Note that no_new_privs does not prevent privilege changes that do not
29involve execve. An appropriately privileged task can still call
30setuid(2) and receive SCM_RIGHTS datagrams.
31
32There are two main use cases for no_new_privs so far:
33
34 - Filters installed for the seccomp mode 2 sandbox persist across
35 execve and can change the behavior of newly-executed programs.
36 Unprivileged users are therefore only allowed to install such filters
37 if no_new_privs is set.
38
39 - By itself, no_new_privs can be used to reduce the attack surface
40 available to an unprivileged user. If everything running with a
41 given uid has no_new_privs set, then that uid will be unable to
42 escalate its privileges by directly attacking setuid, setgid, and
43 fcap-using binaries; it will need to compromise something without the
44 no_new_privs bit set first.
45
46In the future, other potentially dangerous kernel features could become
47available to unprivileged tasks if no_new_privs is set. In principle,
48several options to unshare(2) and clone(2) would be safe when
49no_new_privs is set, and no_new_privs + chroot is considerable less
50dangerous than chroot by itself.
diff --git a/Documentation/stable_kernel_rules.txt b/Documentation/stable_kernel_rules.txt
index f0ab5cf28fca..4a7b54bd37e8 100644
--- a/Documentation/stable_kernel_rules.txt
+++ b/Documentation/stable_kernel_rules.txt
@@ -12,6 +12,12 @@ Rules on what kind of patches are accepted, and which ones are not, into the
12 marked CONFIG_BROKEN), an oops, a hang, data corruption, a real 12 marked CONFIG_BROKEN), an oops, a hang, data corruption, a real
13 security issue, or some "oh, that's not good" issue. In short, something 13 security issue, or some "oh, that's not good" issue. In short, something
14 critical. 14 critical.
15 - Serious issues as reported by a user of a distribution kernel may also
16 be considered if they fix a notable performance or interactivity issue.
17 As these fixes are not as obvious and have a higher risk of a subtle
18 regression they should only be submitted by a distribution kernel
19 maintainer and include an addendum linking to a bugzilla entry if it
20 exists and additional information on the user-visible impact.
15 - New device IDs and quirks are also accepted. 21 - New device IDs and quirks are also accepted.
16 - No "theoretical race condition" issues, unless an explanation of how the 22 - No "theoretical race condition" issues, unless an explanation of how the
17 race can be exploited is also provided. 23 race can be exploited is also provided.
diff --git a/Documentation/vm/frontswap.txt b/Documentation/vm/frontswap.txt
new file mode 100644
index 000000000000..37067cf455f4
--- /dev/null
+++ b/Documentation/vm/frontswap.txt
@@ -0,0 +1,278 @@
1Frontswap provides a "transcendent memory" interface for swap pages.
2In some environments, dramatic performance savings may be obtained because
3swapped pages are saved in RAM (or a RAM-like device) instead of a swap disk.
4
5(Note, frontswap -- and cleancache (merged at 3.0) -- are the "frontends"
6and the only necessary changes to the core kernel for transcendent memory;
7all other supporting code -- the "backends" -- is implemented as drivers.
8See the LWN.net article "Transcendent memory in a nutshell" for a detailed
9overview of frontswap and related kernel parts:
10https://lwn.net/Articles/454795/ )
11
12Frontswap is so named because it can be thought of as the opposite of
13a "backing" store for a swap device. The storage is assumed to be
14a synchronous concurrency-safe page-oriented "pseudo-RAM device" conforming
15to the requirements of transcendent memory (such as Xen's "tmem", or
16in-kernel compressed memory, aka "zcache", or future RAM-like devices);
17this pseudo-RAM device is not directly accessible or addressable by the
18kernel and is of unknown and possibly time-varying size. The driver
19links itself to frontswap by calling frontswap_register_ops to set the
20frontswap_ops funcs appropriately and the functions it provides must
21conform to certain policies as follows:
22
23An "init" prepares the device to receive frontswap pages associated
24with the specified swap device number (aka "type"). A "store" will
25copy the page to transcendent memory and associate it with the type and
26offset associated with the page. A "load" will copy the page, if found,
27from transcendent memory into kernel memory, but will NOT remove the page
28from from transcendent memory. An "invalidate_page" will remove the page
29from transcendent memory and an "invalidate_area" will remove ALL pages
30associated with the swap type (e.g., like swapoff) and notify the "device"
31to refuse further stores with that swap type.
32
33Once a page is successfully stored, a matching load on the page will normally
34succeed. So when the kernel finds itself in a situation where it needs
35to swap out a page, it first attempts to use frontswap. If the store returns
36success, the data has been successfully saved to transcendent memory and
37a disk write and, if the data is later read back, a disk read are avoided.
38If a store returns failure, transcendent memory has rejected the data, and the
39page can be written to swap as usual.
40
41If a backend chooses, frontswap can be configured as a "writethrough
42cache" by calling frontswap_writethrough(). In this mode, the reduction
43in swap device writes is lost (and also a non-trivial performance advantage)
44in order to allow the backend to arbitrarily "reclaim" space used to
45store frontswap pages to more completely manage its memory usage.
46
47Note that if a page is stored and the page already exists in transcendent memory
48(a "duplicate" store), either the store succeeds and the data is overwritten,
49or the store fails AND the page is invalidated. This ensures stale data may
50never be obtained from frontswap.
51
52If properly configured, monitoring of frontswap is done via debugfs in
53the /sys/kernel/debug/frontswap directory. The effectiveness of
54frontswap can be measured (across all swap devices) with:
55
56failed_stores - how many store attempts have failed
57loads - how many loads were attempted (all should succeed)
58succ_stores - how many store attempts have succeeded
59invalidates - how many invalidates were attempted
60
61A backend implementation may provide additional metrics.
62
63FAQ
64
651) Where's the value?
66
67When a workload starts swapping, performance falls through the floor.
68Frontswap significantly increases performance in many such workloads by
69providing a clean, dynamic interface to read and write swap pages to
70"transcendent memory" that is otherwise not directly addressable to the kernel.
71This interface is ideal when data is transformed to a different form
72and size (such as with compression) or secretly moved (as might be
73useful for write-balancing for some RAM-like devices). Swap pages (and
74evicted page-cache pages) are a great use for this kind of slower-than-RAM-
75but-much-faster-than-disk "pseudo-RAM device" and the frontswap (and
76cleancache) interface to transcendent memory provides a nice way to read
77and write -- and indirectly "name" -- the pages.
78
79Frontswap -- and cleancache -- with a fairly small impact on the kernel,
80provides a huge amount of flexibility for more dynamic, flexible RAM
81utilization in various system configurations:
82
83In the single kernel case, aka "zcache", pages are compressed and
84stored in local memory, thus increasing the total anonymous pages
85that can be safely kept in RAM. Zcache essentially trades off CPU
86cycles used in compression/decompression for better memory utilization.
87Benchmarks have shown little or no impact when memory pressure is
88low while providing a significant performance improvement (25%+)
89on some workloads under high memory pressure.
90
91"RAMster" builds on zcache by adding "peer-to-peer" transcendent memory
92support for clustered systems. Frontswap pages are locally compressed
93as in zcache, but then "remotified" to another system's RAM. This
94allows RAM to be dynamically load-balanced back-and-forth as needed,
95i.e. when system A is overcommitted, it can swap to system B, and
96vice versa. RAMster can also be configured as a memory server so
97many servers in a cluster can swap, dynamically as needed, to a single
98server configured with a large amount of RAM... without pre-configuring
99how much of the RAM is available for each of the clients!
100
101In the virtual case, the whole point of virtualization is to statistically
102multiplex physical resources acrosst the varying demands of multiple
103virtual machines. This is really hard to do with RAM and efforts to do
104it well with no kernel changes have essentially failed (except in some
105well-publicized special-case workloads).
106Specifically, the Xen Transcendent Memory backend allows otherwise
107"fallow" hypervisor-owned RAM to not only be "time-shared" between multiple
108virtual machines, but the pages can be compressed and deduplicated to
109optimize RAM utilization. And when guest OS's are induced to surrender
110underutilized RAM (e.g. with "selfballooning"), sudden unexpected
111memory pressure may result in swapping; frontswap allows those pages
112to be swapped to and from hypervisor RAM (if overall host system memory
113conditions allow), thus mitigating the potentially awful performance impact
114of unplanned swapping.
115
116A KVM implementation is underway and has been RFC'ed to lkml. And,
117using frontswap, investigation is also underway on the use of NVM as
118a memory extension technology.
119
1202) Sure there may be performance advantages in some situations, but
121 what's the space/time overhead of frontswap?
122
123If CONFIG_FRONTSWAP is disabled, every frontswap hook compiles into
124nothingness and the only overhead is a few extra bytes per swapon'ed
125swap device. If CONFIG_FRONTSWAP is enabled but no frontswap "backend"
126registers, there is one extra global variable compared to zero for
127every swap page read or written. If CONFIG_FRONTSWAP is enabled
128AND a frontswap backend registers AND the backend fails every "store"
129request (i.e. provides no memory despite claiming it might),
130CPU overhead is still negligible -- and since every frontswap fail
131precedes a swap page write-to-disk, the system is highly likely
132to be I/O bound and using a small fraction of a percent of a CPU
133will be irrelevant anyway.
134
135As for space, if CONFIG_FRONTSWAP is enabled AND a frontswap backend
136registers, one bit is allocated for every swap page for every swap
137device that is swapon'd. This is added to the EIGHT bits (which
138was sixteen until about 2.6.34) that the kernel already allocates
139for every swap page for every swap device that is swapon'd. (Hugh
140Dickins has observed that frontswap could probably steal one of
141the existing eight bits, but let's worry about that minor optimization
142later.) For very large swap disks (which are rare) on a standard
1434K pagesize, this is 1MB per 32GB swap.
144
145When swap pages are stored in transcendent memory instead of written
146out to disk, there is a side effect that this may create more memory
147pressure that can potentially outweigh the other advantages. A
148backend, such as zcache, must implement policies to carefully (but
149dynamically) manage memory limits to ensure this doesn't happen.
150
1513) OK, how about a quick overview of what this frontswap patch does
152 in terms that a kernel hacker can grok?
153
154Let's assume that a frontswap "backend" has registered during
155kernel initialization; this registration indicates that this
156frontswap backend has access to some "memory" that is not directly
157accessible by the kernel. Exactly how much memory it provides is
158entirely dynamic and random.
159
160Whenever a swap-device is swapon'd frontswap_init() is called,
161passing the swap device number (aka "type") as a parameter.
162This notifies frontswap to expect attempts to "store" swap pages
163associated with that number.
164
165Whenever the swap subsystem is readying a page to write to a swap
166device (c.f swap_writepage()), frontswap_store is called. Frontswap
167consults with the frontswap backend and if the backend says it does NOT
168have room, frontswap_store returns -1 and the kernel swaps the page
169to the swap device as normal. Note that the response from the frontswap
170backend is unpredictable to the kernel; it may choose to never accept a
171page, it could accept every ninth page, or it might accept every
172page. But if the backend does accept a page, the data from the page
173has already been copied and associated with the type and offset,
174and the backend guarantees the persistence of the data. In this case,
175frontswap sets a bit in the "frontswap_map" for the swap device
176corresponding to the page offset on the swap device to which it would
177otherwise have written the data.
178
179When the swap subsystem needs to swap-in a page (swap_readpage()),
180it first calls frontswap_load() which checks the frontswap_map to
181see if the page was earlier accepted by the frontswap backend. If
182it was, the page of data is filled from the frontswap backend and
183the swap-in is complete. If not, the normal swap-in code is
184executed to obtain the page of data from the real swap device.
185
186So every time the frontswap backend accepts a page, a swap device read
187and (potentially) a swap device write are replaced by a "frontswap backend
188store" and (possibly) a "frontswap backend loads", which are presumably much
189faster.
190
1914) Can't frontswap be configured as a "special" swap device that is
192 just higher priority than any real swap device (e.g. like zswap,
193 or maybe swap-over-nbd/NFS)?
194
195No. First, the existing swap subsystem doesn't allow for any kind of
196swap hierarchy. Perhaps it could be rewritten to accomodate a hierarchy,
197but this would require fairly drastic changes. Even if it were
198rewritten, the existing swap subsystem uses the block I/O layer which
199assumes a swap device is fixed size and any page in it is linearly
200addressable. Frontswap barely touches the existing swap subsystem,
201and works around the constraints of the block I/O subsystem to provide
202a great deal of flexibility and dynamicity.
203
204For example, the acceptance of any swap page by the frontswap backend is
205entirely unpredictable. This is critical to the definition of frontswap
206backends because it grants completely dynamic discretion to the
207backend. In zcache, one cannot know a priori how compressible a page is.
208"Poorly" compressible pages can be rejected, and "poorly" can itself be
209defined dynamically depending on current memory constraints.
210
211Further, frontswap is entirely synchronous whereas a real swap
212device is, by definition, asynchronous and uses block I/O. The
213block I/O layer is not only unnecessary, but may perform "optimizations"
214that are inappropriate for a RAM-oriented device including delaying
215the write of some pages for a significant amount of time. Synchrony is
216required to ensure the dynamicity of the backend and to avoid thorny race
217conditions that would unnecessarily and greatly complicate frontswap
218and/or the block I/O subsystem. That said, only the initial "store"
219and "load" operations need be synchronous. A separate asynchronous thread
220is free to manipulate the pages stored by frontswap. For example,
221the "remotification" thread in RAMster uses standard asynchronous
222kernel sockets to move compressed frontswap pages to a remote machine.
223Similarly, a KVM guest-side implementation could do in-guest compression
224and use "batched" hypercalls.
225
226In a virtualized environment, the dynamicity allows the hypervisor
227(or host OS) to do "intelligent overcommit". For example, it can
228choose to accept pages only until host-swapping might be imminent,
229then force guests to do their own swapping.
230
231There is a downside to the transcendent memory specifications for
232frontswap: Since any "store" might fail, there must always be a real
233slot on a real swap device to swap the page. Thus frontswap must be
234implemented as a "shadow" to every swapon'd device with the potential
235capability of holding every page that the swap device might have held
236and the possibility that it might hold no pages at all. This means
237that frontswap cannot contain more pages than the total of swapon'd
238swap devices. For example, if NO swap device is configured on some
239installation, frontswap is useless. Swapless portable devices
240can still use frontswap but a backend for such devices must configure
241some kind of "ghost" swap device and ensure that it is never used.
242
2435) Why this weird definition about "duplicate stores"? If a page
244 has been previously successfully stored, can't it always be
245 successfully overwritten?
246
247Nearly always it can, but no, sometimes it cannot. Consider an example
248where data is compressed and the original 4K page has been compressed
249to 1K. Now an attempt is made to overwrite the page with data that
250is non-compressible and so would take the entire 4K. But the backend
251has no more space. In this case, the store must be rejected. Whenever
252frontswap rejects a store that would overwrite, it also must invalidate
253the old data and ensure that it is no longer accessible. Since the
254swap subsystem then writes the new data to the read swap device,
255this is the correct course of action to ensure coherency.
256
2576) What is frontswap_shrink for?
258
259When the (non-frontswap) swap subsystem swaps out a page to a real
260swap device, that page is only taking up low-value pre-allocated disk
261space. But if frontswap has placed a page in transcendent memory, that
262page may be taking up valuable real estate. The frontswap_shrink
263routine allows code outside of the swap subsystem to force pages out
264of the memory managed by frontswap and back into kernel-addressable memory.
265For example, in RAMster, a "suction driver" thread will attempt
266to "repatriate" pages sent to a remote machine back to the local machine;
267this is driven using the frontswap_shrink mechanism when memory pressure
268subsides.
269
2707) Why does the frontswap patch create the new include file swapfile.h?
271
272The frontswap code depends on some swap-subsystem-internal data
273structures that have, over the years, moved back and forth between
274static and global. This seemed a reasonable compromise: Define
275them as global but declare them in a new include file that isn't
276included by the large number of source files that include swap.h.
277
278Dan Magenheimer, last updated April 9, 2012