diff options
author | Jeff Garzik <jgarzik@pobox.com> | 2006-02-09 14:17:05 -0500 |
---|---|---|
committer | Jeff Garzik <jgarzik@pobox.com> | 2006-02-09 14:17:05 -0500 |
commit | 70c07e02625ec46d0ffbfce1acef42d660803528 (patch) | |
tree | f500f1a4f93e72747fb08b0eefabb167dcdc5db9 /Documentation | |
parent | 5d1769ac3d0ea5ff3a286b097c21faaf6a9e6859 (diff) | |
parent | 2746b8623abce815aaae7afc946b1b39f8436f5a (diff) |
Merge branch 'viro'
Diffstat (limited to 'Documentation')
-rw-r--r-- | Documentation/feature-removal-schedule.txt | 9 | ||||
-rw-r--r-- | Documentation/hwmon/f71805f | 105 | ||||
-rw-r--r-- | Documentation/hwmon/it87 | 2 | ||||
-rw-r--r-- | Documentation/hwmon/sysfs-interface | 18 | ||||
-rw-r--r-- | Documentation/i2c/busses/i2c-sis96x (renamed from Documentation/i2c/busses/i2c-sis69x) | 4 | ||||
-rw-r--r-- | Documentation/powerpc/booting-without-of.txt | 8 | ||||
-rw-r--r-- | Documentation/spi/butterfly | 23 | ||||
-rw-r--r-- | Documentation/unshare.txt | 295 |
8 files changed, 454 insertions, 10 deletions
diff --git a/Documentation/feature-removal-schedule.txt b/Documentation/feature-removal-schedule.txt index b47fba58d201..79f0ed9f60de 100644 --- a/Documentation/feature-removal-schedule.txt +++ b/Documentation/feature-removal-schedule.txt | |||
@@ -169,3 +169,12 @@ What: pci_module_init(driver) | |||
169 | When: January 2007 | 169 | When: January 2007 |
170 | Why: Is replaced by pci_register_driver(pci_driver). | 170 | Why: Is replaced by pci_register_driver(pci_driver). |
171 | Who: Richard Knutsson <ricknu-0@student.ltu.se> and Greg Kroah-Hartman <gregkh@suse.de> | 171 | Who: Richard Knutsson <ricknu-0@student.ltu.se> and Greg Kroah-Hartman <gregkh@suse.de> |
172 | |||
173 | --------------------------- | ||
174 | |||
175 | What: I2C interface of the it87 driver | ||
176 | When: January 2007 | ||
177 | Why: The ISA interface is faster and should be always available. The I2C | ||
178 | probing is also known to cause trouble in at least one case (see | ||
179 | bug #5889.) | ||
180 | Who: Jean Delvare <khali@linux-fr.org> | ||
diff --git a/Documentation/hwmon/f71805f b/Documentation/hwmon/f71805f new file mode 100644 index 000000000000..28c5b7d1eb90 --- /dev/null +++ b/Documentation/hwmon/f71805f | |||
@@ -0,0 +1,105 @@ | |||
1 | Kernel driver f71805f | ||
2 | ===================== | ||
3 | |||
4 | Supported chips: | ||
5 | * Fintek F71805F/FG | ||
6 | Prefix: 'f71805f' | ||
7 | Addresses scanned: none, address read from Super I/O config space | ||
8 | Datasheet: Provided by Fintek on request | ||
9 | |||
10 | Author: Jean Delvare <khali@linux-fr.org> | ||
11 | |||
12 | Thanks to Denis Kieft from Barracuda Networks for the donation of a | ||
13 | test system (custom Jetway K8M8MS motherboard, with CPU and RAM) and | ||
14 | for providing initial documentation. | ||
15 | |||
16 | Thanks to Kris Chen from Fintek for answering technical questions and | ||
17 | providing additional documentation. | ||
18 | |||
19 | Thanks to Chris Lin from Jetway for providing wiring schematics and | ||
20 | anwsering technical questions. | ||
21 | |||
22 | |||
23 | Description | ||
24 | ----------- | ||
25 | |||
26 | The Fintek F71805F/FG Super I/O chip includes complete hardware monitoring | ||
27 | capabilities. It can monitor up to 9 voltages (counting its own power | ||
28 | source), 3 fans and 3 temperature sensors. | ||
29 | |||
30 | This chip also has fan controlling features, using either DC or PWM, in | ||
31 | three different modes (one manual, two automatic). The driver doesn't | ||
32 | support these features yet. | ||
33 | |||
34 | The driver assumes that no more than one chip is present, which seems | ||
35 | reasonable. | ||
36 | |||
37 | |||
38 | Voltage Monitoring | ||
39 | ------------------ | ||
40 | |||
41 | Voltages are sampled by an 8-bit ADC with a LSB of 8 mV. The supported | ||
42 | range is thus from 0 to 2.040 V. Voltage values outside of this range | ||
43 | need external resistors. An exception is in0, which is used to monitor | ||
44 | the chip's own power source (+3.3V), and is divided internally by a | ||
45 | factor 2. | ||
46 | |||
47 | The two LSB of the voltage limit registers are not used (always 0), so | ||
48 | you can only set the limits in steps of 32 mV (before scaling). | ||
49 | |||
50 | The wirings and resistor values suggested by Fintek are as follow: | ||
51 | |||
52 | pin expected | ||
53 | name use R1 R2 divider raw val. | ||
54 | |||
55 | in0 VCC VCC3.3V int. int. 2.00 1.65 V | ||
56 | in1 VIN1 VTT1.2V 10K - 1.00 1.20 V | ||
57 | in2 VIN2 VRAM 100K 100K 2.00 ~1.25 V (1) | ||
58 | in3 VIN3 VCHIPSET 47K 100K 1.47 2.24 V (2) | ||
59 | in4 VIN4 VCC5V 200K 47K 5.25 0.95 V | ||
60 | in5 VIN5 +12V 200K 20K 11.00 1.05 V | ||
61 | in6 VIN6 VCC1.5V 10K - 1.00 1.50 V | ||
62 | in7 VIN7 VCORE 10K - 1.00 ~1.40 V (1) | ||
63 | in8 VIN8 VSB5V 200K 47K 1.00 0.95 V | ||
64 | |||
65 | (1) Depends on your hardware setup. | ||
66 | (2) Obviously not correct, swapping R1 and R2 would make more sense. | ||
67 | |||
68 | These values can be used as hints at best, as motherboard manufacturers | ||
69 | are free to use a completely different setup. As a matter of fact, the | ||
70 | Jetway K8M8MS uses a significantly different setup. You will have to | ||
71 | find out documentation about your own motherboard, and edit sensors.conf | ||
72 | accordingly. | ||
73 | |||
74 | Each voltage measured has associated low and high limits, each of which | ||
75 | triggers an alarm when crossed. | ||
76 | |||
77 | |||
78 | Fan Monitoring | ||
79 | -------------- | ||
80 | |||
81 | Fan rotation speeds are reported as 12-bit values from a gated clock | ||
82 | signal. Speeds down to 366 RPM can be measured. There is no theoretical | ||
83 | high limit, but values over 6000 RPM seem to cause problem. The effective | ||
84 | resolution is much lower than you would expect, the step between different | ||
85 | register values being 10 rather than 1. | ||
86 | |||
87 | The chip assumes 2 pulse-per-revolution fans. | ||
88 | |||
89 | An alarm is triggered if the rotation speed drops below a programmable | ||
90 | limit or is too low to be measured. | ||
91 | |||
92 | |||
93 | Temperature Monitoring | ||
94 | ---------------------- | ||
95 | |||
96 | Temperatures are reported in degrees Celsius. Each temperature measured | ||
97 | has a high limit, those crossing triggers an alarm. There is an associated | ||
98 | hysteresis value, below which the temperature has to drop before the | ||
99 | alarm is cleared. | ||
100 | |||
101 | All temperature channels are external, there is no embedded temperature | ||
102 | sensor. Each channel can be used for connecting either a thermal diode | ||
103 | or a thermistor. The driver reports the currently selected mode, but | ||
104 | doesn't allow changing it. In theory, the BIOS should have configured | ||
105 | everything properly. | ||
diff --git a/Documentation/hwmon/it87 b/Documentation/hwmon/it87 index 7f42e441c645..9555be1ed999 100644 --- a/Documentation/hwmon/it87 +++ b/Documentation/hwmon/it87 | |||
@@ -9,7 +9,7 @@ Supported chips: | |||
9 | http://www.ite.com.tw/ | 9 | http://www.ite.com.tw/ |
10 | * IT8712F | 10 | * IT8712F |
11 | Prefix: 'it8712' | 11 | Prefix: 'it8712' |
12 | Addresses scanned: I2C 0x28 - 0x2f | 12 | Addresses scanned: I2C 0x2d |
13 | from Super I/O config space (8 I/O ports) | 13 | from Super I/O config space (8 I/O ports) |
14 | Datasheet: Publicly available at the ITE website | 14 | Datasheet: Publicly available at the ITE website |
15 | http://www.ite.com.tw/ | 15 | http://www.ite.com.tw/ |
diff --git a/Documentation/hwmon/sysfs-interface b/Documentation/hwmon/sysfs-interface index 764cdc5480e7..a0d0ab24288e 100644 --- a/Documentation/hwmon/sysfs-interface +++ b/Documentation/hwmon/sysfs-interface | |||
@@ -179,11 +179,12 @@ temp[1-*]_auto_point[1-*]_temp_hyst | |||
179 | **************** | 179 | **************** |
180 | 180 | ||
181 | temp[1-3]_type Sensor type selection. | 181 | temp[1-3]_type Sensor type selection. |
182 | Integers 1, 2, 3 or thermistor Beta value (3435) | 182 | Integers 1 to 4 or thermistor Beta value (typically 3435) |
183 | Read/Write. | 183 | Read/Write. |
184 | 1: PII/Celeron Diode | 184 | 1: PII/Celeron Diode |
185 | 2: 3904 transistor | 185 | 2: 3904 transistor |
186 | 3: thermal diode | 186 | 3: thermal diode |
187 | 4: thermistor (default/unknown Beta) | ||
187 | Not all types are supported by all chips | 188 | Not all types are supported by all chips |
188 | 189 | ||
189 | temp[1-4]_max Temperature max value. | 190 | temp[1-4]_max Temperature max value. |
@@ -261,6 +262,21 @@ alarms Alarm bitmask. | |||
261 | of individual bits. | 262 | of individual bits. |
262 | Bits are defined in kernel/include/sensors.h. | 263 | Bits are defined in kernel/include/sensors.h. |
263 | 264 | ||
265 | alarms_in Alarm bitmask relative to in (voltage) channels | ||
266 | Read only | ||
267 | A '1' bit means an alarm, LSB corresponds to in0 and so on | ||
268 | Prefered to 'alarms' for newer chips | ||
269 | |||
270 | alarms_fan Alarm bitmask relative to fan channels | ||
271 | Read only | ||
272 | A '1' bit means an alarm, LSB corresponds to fan1 and so on | ||
273 | Prefered to 'alarms' for newer chips | ||
274 | |||
275 | alarms_temp Alarm bitmask relative to temp (temperature) channels | ||
276 | Read only | ||
277 | A '1' bit means an alarm, LSB corresponds to temp1 and so on | ||
278 | Prefered to 'alarms' for newer chips | ||
279 | |||
264 | beep_enable Beep/interrupt enable | 280 | beep_enable Beep/interrupt enable |
265 | 0 to disable. | 281 | 0 to disable. |
266 | 1 to enable. | 282 | 1 to enable. |
diff --git a/Documentation/i2c/busses/i2c-sis69x b/Documentation/i2c/busses/i2c-sis96x index b88953dfd580..00a009b977e9 100644 --- a/Documentation/i2c/busses/i2c-sis69x +++ b/Documentation/i2c/busses/i2c-sis96x | |||
@@ -7,7 +7,7 @@ Supported adapters: | |||
7 | Any combination of these host bridges: | 7 | Any combination of these host bridges: |
8 | 645, 645DX (aka 646), 648, 650, 651, 655, 735, 745, 746 | 8 | 645, 645DX (aka 646), 648, 650, 651, 655, 735, 745, 746 |
9 | and these south bridges: | 9 | and these south bridges: |
10 | 961, 962, 963(L) | 10 | 961, 962, 963(L) |
11 | 11 | ||
12 | Author: Mark M. Hoffman <mhoffman@lightlink.com> | 12 | Author: Mark M. Hoffman <mhoffman@lightlink.com> |
13 | 13 | ||
@@ -29,7 +29,7 @@ The command "lspci" as root should produce something like these lines: | |||
29 | 29 | ||
30 | or perhaps this... | 30 | or perhaps this... |
31 | 31 | ||
32 | 00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645 | 32 | 00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645 |
33 | 00:02.0 ISA bridge: Silicon Integrated Systems [SiS]: Unknown device 0961 | 33 | 00:02.0 ISA bridge: Silicon Integrated Systems [SiS]: Unknown device 0961 |
34 | 00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016 | 34 | 00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016 |
35 | 35 | ||
diff --git a/Documentation/powerpc/booting-without-of.txt b/Documentation/powerpc/booting-without-of.txt index 1284498e847c..54e5f9b1536d 100644 --- a/Documentation/powerpc/booting-without-of.txt +++ b/Documentation/powerpc/booting-without-of.txt | |||
@@ -880,6 +880,10 @@ address which can extend beyond that limit. | |||
880 | - device_type : Should be "soc" | 880 | - device_type : Should be "soc" |
881 | - ranges : Should be defined as specified in 1) to describe the | 881 | - ranges : Should be defined as specified in 1) to describe the |
882 | translation of SOC addresses for memory mapped SOC registers. | 882 | translation of SOC addresses for memory mapped SOC registers. |
883 | - bus-frequency: Contains the bus frequency for the SOC node. | ||
884 | Typically, the value of this field is filled in by the boot | ||
885 | loader. | ||
886 | |||
883 | 887 | ||
884 | Recommended properties: | 888 | Recommended properties: |
885 | 889 | ||
@@ -919,6 +923,7 @@ SOC. | |||
919 | device_type = "soc"; | 923 | device_type = "soc"; |
920 | ranges = <00000000 e0000000 00100000> | 924 | ranges = <00000000 e0000000 00100000> |
921 | reg = <e0000000 00003000>; | 925 | reg = <e0000000 00003000>; |
926 | bus-frequency = <0>; | ||
922 | } | 927 | } |
923 | 928 | ||
924 | 929 | ||
@@ -1170,6 +1175,8 @@ platforms are moved over to use the flattened-device-tree model. | |||
1170 | 1175 | ||
1171 | mdio@24520 { | 1176 | mdio@24520 { |
1172 | reg = <24520 20>; | 1177 | reg = <24520 20>; |
1178 | device_type = "mdio"; | ||
1179 | compatible = "gianfar"; | ||
1173 | 1180 | ||
1174 | ethernet-phy@0 { | 1181 | ethernet-phy@0 { |
1175 | ...... | 1182 | ...... |
@@ -1317,6 +1324,7 @@ not necessary as they are usually the same as the root node. | |||
1317 | device_type = "soc"; | 1324 | device_type = "soc"; |
1318 | ranges = <00000000 e0000000 00100000> | 1325 | ranges = <00000000 e0000000 00100000> |
1319 | reg = <e0000000 00003000>; | 1326 | reg = <e0000000 00003000>; |
1327 | bus-frequency = <0>; | ||
1320 | 1328 | ||
1321 | mdio@24520 { | 1329 | mdio@24520 { |
1322 | reg = <24520 20>; | 1330 | reg = <24520 20>; |
diff --git a/Documentation/spi/butterfly b/Documentation/spi/butterfly index a2e8c8d90e35..9927af7a629c 100644 --- a/Documentation/spi/butterfly +++ b/Documentation/spi/butterfly | |||
@@ -12,13 +12,20 @@ You can make this adapter from an old printer cable and solder things | |||
12 | directly to the Butterfly. Or (if you have the parts and skills) you | 12 | directly to the Butterfly. Or (if you have the parts and skills) you |
13 | can come up with something fancier, providing ciruit protection to the | 13 | can come up with something fancier, providing ciruit protection to the |
14 | Butterfly and the printer port, or with a better power supply than two | 14 | Butterfly and the printer port, or with a better power supply than two |
15 | signal pins from the printer port. | 15 | signal pins from the printer port. Or for that matter, you can use |
16 | similar cables to talk to many AVR boards, even a breadboard. | ||
17 | |||
18 | This is more powerful than "ISP programming" cables since it lets kernel | ||
19 | SPI protocol drivers interact with the AVR, and could even let the AVR | ||
20 | issue interrupts to them. Later, your protocol driver should work | ||
21 | easily with a "real SPI controller", instead of this bitbanger. | ||
16 | 22 | ||
17 | 23 | ||
18 | The first cable connections will hook Linux up to one SPI bus, with the | 24 | The first cable connections will hook Linux up to one SPI bus, with the |
19 | AVR and a DataFlash chip; and to the AVR reset line. This is all you | 25 | AVR and a DataFlash chip; and to the AVR reset line. This is all you |
20 | need to reflash the firmware, and the pins are the standard Atmel "ISP" | 26 | need to reflash the firmware, and the pins are the standard Atmel "ISP" |
21 | connector pins (used also on non-Butterfly AVR boards). | 27 | connector pins (used also on non-Butterfly AVR boards). On the parport |
28 | side this is like "sp12" programming cables. | ||
22 | 29 | ||
23 | Signal Butterfly Parport (DB-25) | 30 | Signal Butterfly Parport (DB-25) |
24 | ------ --------- --------------- | 31 | ------ --------- --------------- |
@@ -40,10 +47,14 @@ by clearing PORTB.[0-3]); (b) configure the mtd_dataflash driver; and | |||
40 | SELECT = J400.PB0/nSS = pin 17/C3,nSELECT | 47 | SELECT = J400.PB0/nSS = pin 17/C3,nSELECT |
41 | GND = J400.GND = pin 24/GND | 48 | GND = J400.GND = pin 24/GND |
42 | 49 | ||
43 | The "USI" controller, using J405, can be used for a second SPI bus. That | 50 | Or you could flash firmware making the AVR into an SPI slave (keeping the |
44 | would let you talk to the AVR over SPI, running firmware that makes it act | 51 | DataFlash in reset) and tweak the spi_butterfly driver to make it bind to |
45 | as an SPI slave, while letting either Linux or the AVR use the DataFlash. | 52 | the driver for your custom SPI-based protocol. |
46 | There are plenty of spare parport pins to wire this one up, such as: | 53 | |
54 | The "USI" controller, using J405, can also be used for a second SPI bus. | ||
55 | That would let you talk to the AVR using custom SPI-with-USI firmware, | ||
56 | while letting either Linux or the AVR use the DataFlash. There are plenty | ||
57 | of spare parport pins to wire this one up, such as: | ||
47 | 58 | ||
48 | Signal Butterfly Parport (DB-25) | 59 | Signal Butterfly Parport (DB-25) |
49 | ------ --------- --------------- | 60 | ------ --------- --------------- |
diff --git a/Documentation/unshare.txt b/Documentation/unshare.txt new file mode 100644 index 000000000000..90a5e9e5bef1 --- /dev/null +++ b/Documentation/unshare.txt | |||
@@ -0,0 +1,295 @@ | |||
1 | |||
2 | unshare system call: | ||
3 | -------------------- | ||
4 | This document describes the new system call, unshare. The document | ||
5 | provides an overview of the feature, why it is needed, how it can | ||
6 | be used, its interface specification, design, implementation and | ||
7 | how it can be tested. | ||
8 | |||
9 | Change Log: | ||
10 | ----------- | ||
11 | version 0.1 Initial document, Janak Desai (janak@us.ibm.com), Jan 11, 2006 | ||
12 | |||
13 | Contents: | ||
14 | --------- | ||
15 | 1) Overview | ||
16 | 2) Benefits | ||
17 | 3) Cost | ||
18 | 4) Requirements | ||
19 | 5) Functional Specification | ||
20 | 6) High Level Design | ||
21 | 7) Low Level Design | ||
22 | 8) Test Specification | ||
23 | 9) Future Work | ||
24 | |||
25 | 1) Overview | ||
26 | ----------- | ||
27 | Most legacy operating system kernels support an abstraction of threads | ||
28 | as multiple execution contexts within a process. These kernels provide | ||
29 | special resources and mechanisms to maintain these "threads". The Linux | ||
30 | kernel, in a clever and simple manner, does not make distinction | ||
31 | between processes and "threads". The kernel allows processes to share | ||
32 | resources and thus they can achieve legacy "threads" behavior without | ||
33 | requiring additional data structures and mechanisms in the kernel. The | ||
34 | power of implementing threads in this manner comes not only from | ||
35 | its simplicity but also from allowing application programmers to work | ||
36 | outside the confinement of all-or-nothing shared resources of legacy | ||
37 | threads. On Linux, at the time of thread creation using the clone system | ||
38 | call, applications can selectively choose which resources to share | ||
39 | between threads. | ||
40 | |||
41 | unshare system call adds a primitive to the Linux thread model that | ||
42 | allows threads to selectively 'unshare' any resources that were being | ||
43 | shared at the time of their creation. unshare was conceptualized by | ||
44 | Al Viro in the August of 2000, on the Linux-Kernel mailing list, as part | ||
45 | of the discussion on POSIX threads on Linux. unshare augments the | ||
46 | usefulness of Linux threads for applications that would like to control | ||
47 | shared resources without creating a new process. unshare is a natural | ||
48 | addition to the set of available primitives on Linux that implement | ||
49 | the concept of process/thread as a virtual machine. | ||
50 | |||
51 | 2) Benefits | ||
52 | ----------- | ||
53 | unshare would be useful to large application frameworks such as PAM | ||
54 | where creating a new process to control sharing/unsharing of process | ||
55 | resources is not possible. Since namespaces are shared by default | ||
56 | when creating a new process using fork or clone, unshare can benefit | ||
57 | even non-threaded applications if they have a need to disassociate | ||
58 | from default shared namespace. The following lists two use-cases | ||
59 | where unshare can be used. | ||
60 | |||
61 | 2.1 Per-security context namespaces | ||
62 | ----------------------------------- | ||
63 | unshare can be used to implement polyinstantiated directories using | ||
64 | the kernel's per-process namespace mechanism. Polyinstantiated directories, | ||
65 | such as per-user and/or per-security context instance of /tmp, /var/tmp or | ||
66 | per-security context instance of a user's home directory, isolate user | ||
67 | processes when working with these directories. Using unshare, a PAM | ||
68 | module can easily setup a private namespace for a user at login. | ||
69 | Polyinstantiated directories are required for Common Criteria certification | ||
70 | with Labeled System Protection Profile, however, with the availability | ||
71 | of shared-tree feature in the Linux kernel, even regular Linux systems | ||
72 | can benefit from setting up private namespaces at login and | ||
73 | polyinstantiating /tmp, /var/tmp and other directories deemed | ||
74 | appropriate by system administrators. | ||
75 | |||
76 | 2.2 unsharing of virtual memory and/or open files | ||
77 | ------------------------------------------------- | ||
78 | Consider a client/server application where the server is processing | ||
79 | client requests by creating processes that share resources such as | ||
80 | virtual memory and open files. Without unshare, the server has to | ||
81 | decide what needs to be shared at the time of creating the process | ||
82 | which services the request. unshare allows the server an ability to | ||
83 | disassociate parts of the context during the servicing of the | ||
84 | request. For large and complex middleware application frameworks, this | ||
85 | ability to unshare after the process was created can be very | ||
86 | useful. | ||
87 | |||
88 | 3) Cost | ||
89 | ------- | ||
90 | In order to not duplicate code and to handle the fact that unshare | ||
91 | works on an active task (as opposed to clone/fork working on a newly | ||
92 | allocated inactive task) unshare had to make minor reorganizational | ||
93 | changes to copy_* functions utilized by clone/fork system call. | ||
94 | There is a cost associated with altering existing, well tested and | ||
95 | stable code to implement a new feature that may not get exercised | ||
96 | extensively in the beginning. However, with proper design and code | ||
97 | review of the changes and creation of an unshare test for the LTP | ||
98 | the benefits of this new feature can exceed its cost. | ||
99 | |||
100 | 4) Requirements | ||
101 | --------------- | ||
102 | unshare reverses sharing that was done using clone(2) system call, | ||
103 | so unshare should have a similar interface as clone(2). That is, | ||
104 | since flags in clone(int flags, void *stack) specifies what should | ||
105 | be shared, similar flags in unshare(int flags) should specify | ||
106 | what should be unshared. Unfortunately, this may appear to invert | ||
107 | the meaning of the flags from the way they are used in clone(2). | ||
108 | However, there was no easy solution that was less confusing and that | ||
109 | allowed incremental context unsharing in future without an ABI change. | ||
110 | |||
111 | unshare interface should accommodate possible future addition of | ||
112 | new context flags without requiring a rebuild of old applications. | ||
113 | If and when new context flags are added, unshare design should allow | ||
114 | incremental unsharing of those resources on an as needed basis. | ||
115 | |||
116 | 5) Functional Specification | ||
117 | --------------------------- | ||
118 | NAME | ||
119 | unshare - disassociate parts of the process execution context | ||
120 | |||
121 | SYNOPSIS | ||
122 | #include <sched.h> | ||
123 | |||
124 | int unshare(int flags); | ||
125 | |||
126 | DESCRIPTION | ||
127 | unshare allows a process to disassociate parts of its execution | ||
128 | context that are currently being shared with other processes. Part | ||
129 | of execution context, such as the namespace, is shared by default | ||
130 | when a new process is created using fork(2), while other parts, | ||
131 | such as the virtual memory, open file descriptors, etc, may be | ||
132 | shared by explicit request to share them when creating a process | ||
133 | using clone(2). | ||
134 | |||
135 | The main use of unshare is to allow a process to control its | ||
136 | shared execution context without creating a new process. | ||
137 | |||
138 | The flags argument specifies one or bitwise-or'ed of several of | ||
139 | the following constants. | ||
140 | |||
141 | CLONE_FS | ||
142 | If CLONE_FS is set, file system information of the caller | ||
143 | is disassociated from the shared file system information. | ||
144 | |||
145 | CLONE_FILES | ||
146 | If CLONE_FILES is set, the file descriptor table of the | ||
147 | caller is disassociated from the shared file descriptor | ||
148 | table. | ||
149 | |||
150 | CLONE_NEWNS | ||
151 | If CLONE_NEWNS is set, the namespace of the caller is | ||
152 | disassociated from the shared namespace. | ||
153 | |||
154 | CLONE_VM | ||
155 | If CLONE_VM is set, the virtual memory of the caller is | ||
156 | disassociated from the shared virtual memory. | ||
157 | |||
158 | RETURN VALUE | ||
159 | On success, zero returned. On failure, -1 is returned and errno is | ||
160 | |||
161 | ERRORS | ||
162 | EPERM CLONE_NEWNS was specified by a non-root process (process | ||
163 | without CAP_SYS_ADMIN). | ||
164 | |||
165 | ENOMEM Cannot allocate sufficient memory to copy parts of caller's | ||
166 | context that need to be unshared. | ||
167 | |||
168 | EINVAL Invalid flag was specified as an argument. | ||
169 | |||
170 | CONFORMING TO | ||
171 | The unshare() call is Linux-specific and should not be used | ||
172 | in programs intended to be portable. | ||
173 | |||
174 | SEE ALSO | ||
175 | clone(2), fork(2) | ||
176 | |||
177 | 6) High Level Design | ||
178 | -------------------- | ||
179 | Depending on the flags argument, the unshare system call allocates | ||
180 | appropriate process context structures, populates it with values from | ||
181 | the current shared version, associates newly duplicated structures | ||
182 | with the current task structure and releases corresponding shared | ||
183 | versions. Helper functions of clone (copy_*) could not be used | ||
184 | directly by unshare because of the following two reasons. | ||
185 | 1) clone operates on a newly allocated not-yet-active task | ||
186 | structure, where as unshare operates on the current active | ||
187 | task. Therefore unshare has to take appropriate task_lock() | ||
188 | before associating newly duplicated context structures | ||
189 | 2) unshare has to allocate and duplicate all context structures | ||
190 | that are being unshared, before associating them with the | ||
191 | current task and releasing older shared structures. Failure | ||
192 | do so will create race conditions and/or oops when trying | ||
193 | to backout due to an error. Consider the case of unsharing | ||
194 | both virtual memory and namespace. After successfully unsharing | ||
195 | vm, if the system call encounters an error while allocating | ||
196 | new namespace structure, the error return code will have to | ||
197 | reverse the unsharing of vm. As part of the reversal the | ||
198 | system call will have to go back to older, shared, vm | ||
199 | structure, which may not exist anymore. | ||
200 | |||
201 | Therefore code from copy_* functions that allocated and duplicated | ||
202 | current context structure was moved into new dup_* functions. Now, | ||
203 | copy_* functions call dup_* functions to allocate and duplicate | ||
204 | appropriate context structures and then associate them with the | ||
205 | task structure that is being constructed. unshare system call on | ||
206 | the other hand performs the following: | ||
207 | 1) Check flags to force missing, but implied, flags | ||
208 | 2) For each context structure, call the corresponding unshare | ||
209 | helper function to allocate and duplicate a new context | ||
210 | structure, if the appropriate bit is set in the flags argument. | ||
211 | 3) If there is no error in allocation and duplication and there | ||
212 | are new context structures then lock the current task structure, | ||
213 | associate new context structures with the current task structure, | ||
214 | and release the lock on the current task structure. | ||
215 | 4) Appropriately release older, shared, context structures. | ||
216 | |||
217 | 7) Low Level Design | ||
218 | ------------------- | ||
219 | Implementation of unshare can be grouped in the following 4 different | ||
220 | items: | ||
221 | a) Reorganization of existing copy_* functions | ||
222 | b) unshare system call service function | ||
223 | c) unshare helper functions for each different process context | ||
224 | d) Registration of system call number for different architectures | ||
225 | |||
226 | 7.1) Reorganization of copy_* functions | ||
227 | Each copy function such as copy_mm, copy_namespace, copy_files, | ||
228 | etc, had roughly two components. The first component allocated | ||
229 | and duplicated the appropriate structure and the second component | ||
230 | linked it to the task structure passed in as an argument to the copy | ||
231 | function. The first component was split into its own function. | ||
232 | These dup_* functions allocated and duplicated the appropriate | ||
233 | context structure. The reorganized copy_* functions invoked | ||
234 | their corresponding dup_* functions and then linked the newly | ||
235 | duplicated structures to the task structure with which the | ||
236 | copy function was called. | ||
237 | |||
238 | 7.2) unshare system call service function | ||
239 | * Check flags | ||
240 | Force implied flags. If CLONE_THREAD is set force CLONE_VM. | ||
241 | If CLONE_VM is set, force CLONE_SIGHAND. If CLONE_SIGHAND is | ||
242 | set and signals are also being shared, force CLONE_THREAD. If | ||
243 | CLONE_NEWNS is set, force CLONE_FS. | ||
244 | * For each context flag, invoke the corresponding unshare_* | ||
245 | helper routine with flags passed into the system call and a | ||
246 | reference to pointer pointing the new unshared structure | ||
247 | * If any new structures are created by unshare_* helper | ||
248 | functions, take the task_lock() on the current task, | ||
249 | modify appropriate context pointers, and release the | ||
250 | task lock. | ||
251 | * For all newly unshared structures, release the corresponding | ||
252 | older, shared, structures. | ||
253 | |||
254 | 7.3) unshare_* helper functions | ||
255 | For unshare_* helpers corresponding to CLONE_SYSVSEM, CLONE_SIGHAND, | ||
256 | and CLONE_THREAD, return -EINVAL since they are not implemented yet. | ||
257 | For others, check the flag value to see if the unsharing is | ||
258 | required for that structure. If it is, invoke the corresponding | ||
259 | dup_* function to allocate and duplicate the structure and return | ||
260 | a pointer to it. | ||
261 | |||
262 | 7.4) Appropriately modify architecture specific code to register the | ||
263 | the new system call. | ||
264 | |||
265 | 8) Test Specification | ||
266 | --------------------- | ||
267 | The test for unshare should test the following: | ||
268 | 1) Valid flags: Test to check that clone flags for signal and | ||
269 | signal handlers, for which unsharing is not implemented | ||
270 | yet, return -EINVAL. | ||
271 | 2) Missing/implied flags: Test to make sure that if unsharing | ||
272 | namespace without specifying unsharing of filesystem, correctly | ||
273 | unshares both namespace and filesystem information. | ||
274 | 3) For each of the four (namespace, filesystem, files and vm) | ||
275 | supported unsharing, verify that the system call correctly | ||
276 | unshares the appropriate structure. Verify that unsharing | ||
277 | them individually as well as in combination with each | ||
278 | other works as expected. | ||
279 | 4) Concurrent execution: Use shared memory segments and futex on | ||
280 | an address in the shm segment to synchronize execution of | ||
281 | about 10 threads. Have a couple of threads execute execve, | ||
282 | a couple _exit and the rest unshare with different combination | ||
283 | of flags. Verify that unsharing is performed as expected and | ||
284 | that there are no oops or hangs. | ||
285 | |||
286 | 9) Future Work | ||
287 | -------------- | ||
288 | The current implementation of unshare does not allow unsharing of | ||
289 | signals and signal handlers. Signals are complex to begin with and | ||
290 | to unshare signals and/or signal handlers of a currently running | ||
291 | process is even more complex. If in the future there is a specific | ||
292 | need to allow unsharing of signals and/or signal handlers, it can | ||
293 | be incrementally added to unshare without affecting legacy | ||
294 | applications using unshare. | ||
295 | |||