diff options
Diffstat (limited to 'Documentation')
-rw-r--r-- | Documentation/DMA-mapping.txt | 2 | ||||
-rw-r--r-- | Documentation/RCU/whatisRCU.txt | 2 | ||||
-rw-r--r-- | Documentation/block/biodoc.txt | 14 | ||||
-rw-r--r-- | Documentation/cachetlb.txt | 21 | ||||
-rw-r--r-- | Documentation/cpu-hotplug.txt | 4 | ||||
-rw-r--r-- | Documentation/cputopology.txt | 4 | ||||
-rw-r--r-- | Documentation/drivers/edac/edac.txt | 34 | ||||
-rw-r--r-- | Documentation/filesystems/00-INDEX | 54 | ||||
-rw-r--r-- | Documentation/ioctl-number.txt | 2 | ||||
-rw-r--r-- | Documentation/m68k/README.buddha | 2 | ||||
-rw-r--r-- | Documentation/networking/ifenslave.c | 2 | ||||
-rw-r--r-- | Documentation/networking/vortex.txt | 81 | ||||
-rw-r--r-- | Documentation/pnp.txt | 3 | ||||
-rw-r--r-- | Documentation/robust-futex-ABI.txt | 182 | ||||
-rw-r--r-- | Documentation/robust-futexes.txt | 218 | ||||
-rw-r--r-- | Documentation/rpc-cache.txt | 121 | ||||
-rw-r--r-- | Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl | 2 |
17 files changed, 628 insertions, 120 deletions
diff --git a/Documentation/DMA-mapping.txt b/Documentation/DMA-mapping.txt index 684557474c15..ee4bb73683cd 100644 --- a/Documentation/DMA-mapping.txt +++ b/Documentation/DMA-mapping.txt | |||
@@ -199,6 +199,8 @@ address during PCI bus mastering you might do something like: | |||
199 | "mydev: 24-bit DMA addressing not available.\n"); | 199 | "mydev: 24-bit DMA addressing not available.\n"); |
200 | goto ignore_this_device; | 200 | goto ignore_this_device; |
201 | } | 201 | } |
202 | [Better use DMA_24BIT_MASK instead of 0x00ffffff. | ||
203 | See linux/include/dma-mapping.h for reference.] | ||
202 | 204 | ||
203 | When pci_set_dma_mask() is successful, and returns zero, the PCI layer | 205 | When pci_set_dma_mask() is successful, and returns zero, the PCI layer |
204 | saves away this mask you have provided. The PCI layer will use this | 206 | saves away this mask you have provided. The PCI layer will use this |
diff --git a/Documentation/RCU/whatisRCU.txt b/Documentation/RCU/whatisRCU.txt index b4ea51ad3610..07cb93b82ba9 100644 --- a/Documentation/RCU/whatisRCU.txt +++ b/Documentation/RCU/whatisRCU.txt | |||
@@ -605,7 +605,7 @@ are the same as those shown in the preceding section, so they are omitted. | |||
605 | { | 605 | { |
606 | int cpu; | 606 | int cpu; |
607 | 607 | ||
608 | for_each_cpu(cpu) | 608 | for_each_possible_cpu(cpu) |
609 | run_on(cpu); | 609 | run_on(cpu); |
610 | } | 610 | } |
611 | 611 | ||
diff --git a/Documentation/block/biodoc.txt b/Documentation/block/biodoc.txt index 8e63831971d5..f989a9e839b4 100644 --- a/Documentation/block/biodoc.txt +++ b/Documentation/block/biodoc.txt | |||
@@ -132,8 +132,18 @@ Some new queue property settings: | |||
132 | limit. No highmem default. | 132 | limit. No highmem default. |
133 | 133 | ||
134 | blk_queue_max_sectors(q, max_sectors) | 134 | blk_queue_max_sectors(q, max_sectors) |
135 | Maximum size request you can handle in units of 512 byte | 135 | Sets two variables that limit the size of the request. |
136 | sectors. 255 default. | 136 | |
137 | - The request queue's max_sectors, which is a soft size in | ||
138 | in units of 512 byte sectors, and could be dynamically varied | ||
139 | by the core kernel. | ||
140 | |||
141 | - The request queue's max_hw_sectors, which is a hard limit | ||
142 | and reflects the maximum size request a driver can handle | ||
143 | in units of 512 byte sectors. | ||
144 | |||
145 | The default for both max_sectors and max_hw_sectors is | ||
146 | 255. The upper limit of max_sectors is 1024. | ||
137 | 147 | ||
138 | blk_queue_max_phys_segments(q, max_segments) | 148 | blk_queue_max_phys_segments(q, max_segments) |
139 | Maximum physical segments you can handle in a request. 128 | 149 | Maximum physical segments you can handle in a request. 128 |
diff --git a/Documentation/cachetlb.txt b/Documentation/cachetlb.txt index 4ae418889b88..53245c429f7d 100644 --- a/Documentation/cachetlb.txt +++ b/Documentation/cachetlb.txt | |||
@@ -362,6 +362,27 @@ maps this page at its virtual address. | |||
362 | likely that you will need to flush the instruction cache | 362 | likely that you will need to flush the instruction cache |
363 | for copy_to_user_page(). | 363 | for copy_to_user_page(). |
364 | 364 | ||
365 | void flush_anon_page(struct page *page, unsigned long vmaddr) | ||
366 | When the kernel needs to access the contents of an anonymous | ||
367 | page, it calls this function (currently only | ||
368 | get_user_pages()). Note: flush_dcache_page() deliberately | ||
369 | doesn't work for an anonymous page. The default | ||
370 | implementation is a nop (and should remain so for all coherent | ||
371 | architectures). For incoherent architectures, it should flush | ||
372 | the cache of the page at vmaddr in the current user process. | ||
373 | |||
374 | void flush_kernel_dcache_page(struct page *page) | ||
375 | When the kernel needs to modify a user page is has obtained | ||
376 | with kmap, it calls this function after all modifications are | ||
377 | complete (but before kunmapping it) to bring the underlying | ||
378 | page up to date. It is assumed here that the user has no | ||
379 | incoherent cached copies (i.e. the original page was obtained | ||
380 | from a mechanism like get_user_pages()). The default | ||
381 | implementation is a nop and should remain so on all coherent | ||
382 | architectures. On incoherent architectures, this should flush | ||
383 | the kernel cache for page (using page_address(page)). | ||
384 | |||
385 | |||
365 | void flush_icache_range(unsigned long start, unsigned long end) | 386 | void flush_icache_range(unsigned long start, unsigned long end) |
366 | When the kernel stores into addresses that it will execute | 387 | When the kernel stores into addresses that it will execute |
367 | out of (eg when loading modules), this function is called. | 388 | out of (eg when loading modules), this function is called. |
diff --git a/Documentation/cpu-hotplug.txt b/Documentation/cpu-hotplug.txt index 57a09f99ecb0..1bcf69996c9d 100644 --- a/Documentation/cpu-hotplug.txt +++ b/Documentation/cpu-hotplug.txt | |||
@@ -97,13 +97,13 @@ at which time hotplug is disabled. | |||
97 | 97 | ||
98 | You really dont need to manipulate any of the system cpu maps. They should | 98 | You really dont need to manipulate any of the system cpu maps. They should |
99 | be read-only for most use. When setting up per-cpu resources almost always use | 99 | be read-only for most use. When setting up per-cpu resources almost always use |
100 | cpu_possible_map/for_each_cpu() to iterate. | 100 | cpu_possible_map/for_each_possible_cpu() to iterate. |
101 | 101 | ||
102 | Never use anything other than cpumask_t to represent bitmap of CPUs. | 102 | Never use anything other than cpumask_t to represent bitmap of CPUs. |
103 | 103 | ||
104 | #include <linux/cpumask.h> | 104 | #include <linux/cpumask.h> |
105 | 105 | ||
106 | for_each_cpu - Iterate over cpu_possible_map | 106 | for_each_possible_cpu - Iterate over cpu_possible_map |
107 | for_each_online_cpu - Iterate over cpu_online_map | 107 | for_each_online_cpu - Iterate over cpu_online_map |
108 | for_each_present_cpu - Iterate over cpu_present_map | 108 | for_each_present_cpu - Iterate over cpu_present_map |
109 | for_each_cpu_mask(x,mask) - Iterate over some random collection of cpu mask. | 109 | for_each_cpu_mask(x,mask) - Iterate over some random collection of cpu mask. |
diff --git a/Documentation/cputopology.txt b/Documentation/cputopology.txt index ff280e2e1613..2b28e9ec4e3a 100644 --- a/Documentation/cputopology.txt +++ b/Documentation/cputopology.txt | |||
@@ -1,5 +1,5 @@ | |||
1 | 1 | ||
2 | Export cpu topology info by sysfs. Items (attributes) are similar | 2 | Export cpu topology info via sysfs. Items (attributes) are similar |
3 | to /proc/cpuinfo. | 3 | to /proc/cpuinfo. |
4 | 4 | ||
5 | 1) /sys/devices/system/cpu/cpuX/topology/physical_package_id: | 5 | 1) /sys/devices/system/cpu/cpuX/topology/physical_package_id: |
@@ -12,7 +12,7 @@ represent the thread siblings to cpu X in the same core; | |||
12 | represent the thread siblings to cpu X in the same physical package; | 12 | represent the thread siblings to cpu X in the same physical package; |
13 | 13 | ||
14 | To implement it in an architecture-neutral way, a new source file, | 14 | To implement it in an architecture-neutral way, a new source file, |
15 | driver/base/topology.c, is to export the 5 attributes. | 15 | drivers/base/topology.c, is to export the 4 attributes. |
16 | 16 | ||
17 | If one architecture wants to support this feature, it just needs to | 17 | If one architecture wants to support this feature, it just needs to |
18 | implement 4 defines, typically in file include/asm-XXX/topology.h. | 18 | implement 4 defines, typically in file include/asm-XXX/topology.h. |
diff --git a/Documentation/drivers/edac/edac.txt b/Documentation/drivers/edac/edac.txt index d37191fe5681..70d96a62e5e1 100644 --- a/Documentation/drivers/edac/edac.txt +++ b/Documentation/drivers/edac/edac.txt | |||
@@ -21,7 +21,7 @@ within the computer system. In the initial release, memory Correctable Errors | |||
21 | 21 | ||
22 | Detecting CE events, then harvesting those events and reporting them, | 22 | Detecting CE events, then harvesting those events and reporting them, |
23 | CAN be a predictor of future UE events. With CE events, the system can | 23 | CAN be a predictor of future UE events. With CE events, the system can |
24 | continue to operate, but with less safety. Preventive maintainence and | 24 | continue to operate, but with less safety. Preventive maintenance and |
25 | proactive part replacement of memory DIMMs exhibiting CEs can reduce | 25 | proactive part replacement of memory DIMMs exhibiting CEs can reduce |
26 | the likelihood of the dreaded UE events and system 'panics'. | 26 | the likelihood of the dreaded UE events and system 'panics'. |
27 | 27 | ||
@@ -29,13 +29,13 @@ the likelihood of the dreaded UE events and system 'panics'. | |||
29 | In addition, PCI Bus Parity and SERR Errors are scanned for on PCI devices | 29 | In addition, PCI Bus Parity and SERR Errors are scanned for on PCI devices |
30 | in order to determine if errors are occurring on data transfers. | 30 | in order to determine if errors are occurring on data transfers. |
31 | The presence of PCI Parity errors must be examined with a grain of salt. | 31 | The presence of PCI Parity errors must be examined with a grain of salt. |
32 | There are several addin adapters that do NOT follow the PCI specification | 32 | There are several add-in adapters that do NOT follow the PCI specification |
33 | with regards to Parity generation and reporting. The specification says | 33 | with regards to Parity generation and reporting. The specification says |
34 | the vendor should tie the parity status bits to 0 if they do not intend | 34 | the vendor should tie the parity status bits to 0 if they do not intend |
35 | to generate parity. Some vendors do not do this, and thus the parity bit | 35 | to generate parity. Some vendors do not do this, and thus the parity bit |
36 | can "float" giving false positives. | 36 | can "float" giving false positives. |
37 | 37 | ||
38 | The PCI Parity EDAC device has the ability to "skip" known flakey | 38 | The PCI Parity EDAC device has the ability to "skip" known flaky |
39 | cards during the parity scan. These are set by the parity "blacklist" | 39 | cards during the parity scan. These are set by the parity "blacklist" |
40 | interface in the sysfs for PCI Parity. (See the PCI section in the sysfs | 40 | interface in the sysfs for PCI Parity. (See the PCI section in the sysfs |
41 | section below.) There is also a parity "whitelist" which is used as | 41 | section below.) There is also a parity "whitelist" which is used as |
@@ -101,7 +101,7 @@ Memory Controller (mc) Model | |||
101 | 101 | ||
102 | First a background on the memory controller's model abstracted in EDAC. | 102 | First a background on the memory controller's model abstracted in EDAC. |
103 | Each mc device controls a set of DIMM memory modules. These modules are | 103 | Each mc device controls a set of DIMM memory modules. These modules are |
104 | layed out in a Chip-Select Row (csrowX) and Channel table (chX). There can | 104 | laid out in a Chip-Select Row (csrowX) and Channel table (chX). There can |
105 | be multiple csrows and two channels. | 105 | be multiple csrows and two channels. |
106 | 106 | ||
107 | Memory controllers allow for several csrows, with 8 csrows being a typical value. | 107 | Memory controllers allow for several csrows, with 8 csrows being a typical value. |
@@ -131,7 +131,7 @@ for memory DIMMs: | |||
131 | DIMM_B1 | 131 | DIMM_B1 |
132 | 132 | ||
133 | Labels for these slots are usually silk screened on the motherboard. Slots | 133 | Labels for these slots are usually silk screened on the motherboard. Slots |
134 | labeled 'A' are channel 0 in this example. Slots labled 'B' | 134 | labeled 'A' are channel 0 in this example. Slots labeled 'B' |
135 | are channel 1. Notice that there are two csrows possible on a | 135 | are channel 1. Notice that there are two csrows possible on a |
136 | physical DIMM. These csrows are allocated their csrow assignment | 136 | physical DIMM. These csrows are allocated their csrow assignment |
137 | based on the slot into which the memory DIMM is placed. Thus, when 1 DIMM | 137 | based on the slot into which the memory DIMM is placed. Thus, when 1 DIMM |
@@ -140,7 +140,7 @@ is placed in each Channel, the csrows cross both DIMMs. | |||
140 | Memory DIMMs come single or dual "ranked". A rank is a populated csrow. | 140 | Memory DIMMs come single or dual "ranked". A rank is a populated csrow. |
141 | Thus, 2 single ranked DIMMs, placed in slots DIMM_A0 and DIMM_B0 above | 141 | Thus, 2 single ranked DIMMs, placed in slots DIMM_A0 and DIMM_B0 above |
142 | will have 1 csrow, csrow0. csrow1 will be empty. On the other hand, | 142 | will have 1 csrow, csrow0. csrow1 will be empty. On the other hand, |
143 | when 2 dual ranked DIMMs are similiaryly placed, then both csrow0 and | 143 | when 2 dual ranked DIMMs are similarly placed, then both csrow0 and |
144 | csrow1 will be populated. The pattern repeats itself for csrow2 and | 144 | csrow1 will be populated. The pattern repeats itself for csrow2 and |
145 | csrow3. | 145 | csrow3. |
146 | 146 | ||
@@ -246,7 +246,7 @@ Module Version read-only attribute file: | |||
246 | 246 | ||
247 | 'mc_version' | 247 | 'mc_version' |
248 | 248 | ||
249 | The EDAC CORE modules's version and compile date are shown here to | 249 | The EDAC CORE module's version and compile date are shown here to |
250 | indicate what EDAC is running. | 250 | indicate what EDAC is running. |
251 | 251 | ||
252 | 252 | ||
@@ -423,7 +423,7 @@ Total memory managed by this csrow attribute file: | |||
423 | 'size_mb' | 423 | 'size_mb' |
424 | 424 | ||
425 | This attribute file displays, in count of megabytes, of memory | 425 | This attribute file displays, in count of megabytes, of memory |
426 | that this csrow contatins. | 426 | that this csrow contains. |
427 | 427 | ||
428 | 428 | ||
429 | Memory Type attribute file: | 429 | Memory Type attribute file: |
@@ -557,7 +557,7 @@ On Header Type 00 devices the primary status is looked at | |||
557 | for any parity error regardless of whether Parity is enabled on the | 557 | for any parity error regardless of whether Parity is enabled on the |
558 | device. (The spec indicates parity is generated in some cases). | 558 | device. (The spec indicates parity is generated in some cases). |
559 | On Header Type 01 bridges, the secondary status register is also | 559 | On Header Type 01 bridges, the secondary status register is also |
560 | looked at to see if parity ocurred on the bus on the other side of | 560 | looked at to see if parity occurred on the bus on the other side of |
561 | the bridge. | 561 | the bridge. |
562 | 562 | ||
563 | 563 | ||
@@ -588,7 +588,7 @@ Panic on PCI PARITY Error: | |||
588 | 'panic_on_pci_parity' | 588 | 'panic_on_pci_parity' |
589 | 589 | ||
590 | 590 | ||
591 | This control files enables or disables panic'ing when a parity | 591 | This control files enables or disables panicking when a parity |
592 | error has been detected. | 592 | error has been detected. |
593 | 593 | ||
594 | 594 | ||
@@ -616,12 +616,12 @@ PCI Device Whitelist: | |||
616 | 616 | ||
617 | This control file allows for an explicit list of PCI devices to be | 617 | This control file allows for an explicit list of PCI devices to be |
618 | scanned for parity errors. Only devices found on this list will | 618 | scanned for parity errors. Only devices found on this list will |
619 | be examined. The list is a line of hexadecimel VENDOR and DEVICE | 619 | be examined. The list is a line of hexadecimal VENDOR and DEVICE |
620 | ID tuples: | 620 | ID tuples: |
621 | 621 | ||
622 | 1022:7450,1434:16a6 | 622 | 1022:7450,1434:16a6 |
623 | 623 | ||
624 | One or more can be inserted, seperated by a comma. | 624 | One or more can be inserted, separated by a comma. |
625 | 625 | ||
626 | To write the above list doing the following as one command line: | 626 | To write the above list doing the following as one command line: |
627 | 627 | ||
@@ -639,11 +639,11 @@ PCI Device Blacklist: | |||
639 | 639 | ||
640 | This control file allows for a list of PCI devices to be | 640 | This control file allows for a list of PCI devices to be |
641 | skipped for scanning. | 641 | skipped for scanning. |
642 | The list is a line of hexadecimel VENDOR and DEVICE ID tuples: | 642 | The list is a line of hexadecimal VENDOR and DEVICE ID tuples: |
643 | 643 | ||
644 | 1022:7450,1434:16a6 | 644 | 1022:7450,1434:16a6 |
645 | 645 | ||
646 | One or more can be inserted, seperated by a comma. | 646 | One or more can be inserted, separated by a comma. |
647 | 647 | ||
648 | To write the above list doing the following as one command line: | 648 | To write the above list doing the following as one command line: |
649 | 649 | ||
@@ -651,14 +651,14 @@ PCI Device Blacklist: | |||
651 | > /sys/devices/system/edac/pci/pci_parity_blacklist | 651 | > /sys/devices/system/edac/pci/pci_parity_blacklist |
652 | 652 | ||
653 | 653 | ||
654 | To display what the whitelist current contatins, | 654 | To display what the whitelist currently contains, |
655 | simply 'cat' the same file. | 655 | simply 'cat' the same file. |
656 | 656 | ||
657 | ======================================================================= | 657 | ======================================================================= |
658 | 658 | ||
659 | PCI Vendor and Devices IDs can be obtained with the lspci command. Using | 659 | PCI Vendor and Devices IDs can be obtained with the lspci command. Using |
660 | the -n option lspci will display the vendor and device IDs. The system | 660 | the -n option lspci will display the vendor and device IDs. The system |
661 | adminstrator will have to determine which devices should be scanned or | 661 | administrator will have to determine which devices should be scanned or |
662 | skipped. | 662 | skipped. |
663 | 663 | ||
664 | 664 | ||
@@ -669,5 +669,5 @@ Turn OFF a whitelist by an empty echo command: | |||
669 | 669 | ||
670 | echo > /sys/devices/system/edac/pci/pci_parity_whitelist | 670 | echo > /sys/devices/system/edac/pci/pci_parity_whitelist |
671 | 671 | ||
672 | and any previous blacklist will be utililzed. | 672 | and any previous blacklist will be utilized. |
673 | 673 | ||
diff --git a/Documentation/filesystems/00-INDEX b/Documentation/filesystems/00-INDEX index 74052d22d868..66fdc0744fe0 100644 --- a/Documentation/filesystems/00-INDEX +++ b/Documentation/filesystems/00-INDEX | |||
@@ -1,27 +1,47 @@ | |||
1 | 00-INDEX | 1 | 00-INDEX |
2 | - this file (info on some of the filesystems supported by linux). | 2 | - this file (info on some of the filesystems supported by linux). |
3 | Exporting | ||
4 | - explanation of how to make filesystems exportable. | ||
3 | Locking | 5 | Locking |
4 | - info on locking rules as they pertain to Linux VFS. | 6 | - info on locking rules as they pertain to Linux VFS. |
5 | adfs.txt | 7 | adfs.txt |
6 | - info and mount options for the Acorn Advanced Disc Filing System. | 8 | - info and mount options for the Acorn Advanced Disc Filing System. |
9 | afs.txt | ||
10 | - info and examples for the distributed AFS (Andrew File System) fs. | ||
7 | affs.txt | 11 | affs.txt |
8 | - info and mount options for the Amiga Fast File System. | 12 | - info and mount options for the Amiga Fast File System. |
13 | automount-support.txt | ||
14 | - information about filesystem automount support. | ||
15 | befs.txt | ||
16 | - information about the BeOS filesystem for Linux. | ||
9 | bfs.txt | 17 | bfs.txt |
10 | - info for the SCO UnixWare Boot Filesystem (BFS). | 18 | - info for the SCO UnixWare Boot Filesystem (BFS). |
11 | cifs.txt | 19 | cifs.txt |
12 | - description of the CIFS filesystem | 20 | - description of the CIFS filesystem. |
13 | coda.txt | 21 | coda.txt |
14 | - description of the CODA filesystem. | 22 | - description of the CODA filesystem. |
15 | configfs/ | 23 | configfs/ |
16 | - directory containing configfs documentation and example code. | 24 | - directory containing configfs documentation and example code. |
17 | cramfs.txt | 25 | cramfs.txt |
18 | - info on the cram filesystem for small storage (ROMs etc) | 26 | - info on the cram filesystem for small storage (ROMs etc). |
27 | dentry-locking.txt | ||
28 | - info on the RCU-based dcache locking model. | ||
19 | devfs/ | 29 | devfs/ |
20 | - directory containing devfs documentation. | 30 | - directory containing devfs documentation. |
31 | directory-locking | ||
32 | - info about the locking scheme used for directory operations. | ||
21 | dlmfs.txt | 33 | dlmfs.txt |
22 | - info on the userspace interface to the OCFS2 DLM. | 34 | - info on the userspace interface to the OCFS2 DLM. |
23 | ext2.txt | 35 | ext2.txt |
24 | - info, mount options and specifications for the Ext2 filesystem. | 36 | - info, mount options and specifications for the Ext2 filesystem. |
37 | ext3.txt | ||
38 | - info, mount options and specifications for the Ext3 filesystem. | ||
39 | files.txt | ||
40 | - info on file management in the Linux kernel. | ||
41 | fuse.txt | ||
42 | - info on the Filesystem in User SpacE including mount options. | ||
43 | hfs.txt | ||
44 | - info on the Macintosh HFS Filesystem for Linux. | ||
25 | hpfs.txt | 45 | hpfs.txt |
26 | - info and mount options for the OS/2 HPFS. | 46 | - info and mount options for the OS/2 HPFS. |
27 | isofs.txt | 47 | isofs.txt |
@@ -32,23 +52,43 @@ ncpfs.txt | |||
32 | - info on Novell Netware(tm) filesystem using NCP protocol. | 52 | - info on Novell Netware(tm) filesystem using NCP protocol. |
33 | ntfs.txt | 53 | ntfs.txt |
34 | - info and mount options for the NTFS filesystem (Windows NT). | 54 | - info and mount options for the NTFS filesystem (Windows NT). |
35 | proc.txt | ||
36 | - info on Linux's /proc filesystem. | ||
37 | ocfs2.txt | 55 | ocfs2.txt |
38 | - info and mount options for the OCFS2 clustered filesystem. | 56 | - info and mount options for the OCFS2 clustered filesystem. |
57 | porting | ||
58 | - various information on filesystem porting. | ||
59 | proc.txt | ||
60 | - info on Linux's /proc filesystem. | ||
61 | ramfs-rootfs-initramfs.txt | ||
62 | - info on the 'in memory' filesystems ramfs, rootfs and initramfs. | ||
63 | reiser4.txt | ||
64 | - info on the Reiser4 filesystem based on dancing tree algorithms. | ||
65 | relayfs.txt | ||
66 | - info on relayfs, for efficient streaming from kernel to user space. | ||
39 | romfs.txt | 67 | romfs.txt |
40 | - Description of the ROMFS filesystem. | 68 | - description of the ROMFS filesystem. |
41 | smbfs.txt | 69 | smbfs.txt |
42 | - info on using filesystems with the SMB protocol (Windows 3.11 and NT) | 70 | - info on using filesystems with the SMB protocol (Win 3.11 and NT). |
71 | spufs.txt | ||
72 | - info and mount options for the SPU filesystem used on Cell. | ||
73 | sysfs-pci.txt | ||
74 | - info on accessing PCI device resources through sysfs. | ||
75 | sysfs.txt | ||
76 | - info on sysfs, a ram-based filesystem for exporting kernel objects. | ||
43 | sysv-fs.txt | 77 | sysv-fs.txt |
44 | - info on the SystemV/V7/Xenix/Coherent filesystem. | 78 | - info on the SystemV/V7/Xenix/Coherent filesystem. |
79 | tmpfs.txt | ||
80 | - info on tmpfs, a filesystem that holds all files in virtual memory. | ||
45 | udf.txt | 81 | udf.txt |
46 | - info and mount options for the UDF filesystem. | 82 | - info and mount options for the UDF filesystem. |
47 | ufs.txt | 83 | ufs.txt |
48 | - info on the ufs filesystem. | 84 | - info on the ufs filesystem. |
85 | v9fs.txt | ||
86 | - v9fs is a Unix implementation of the Plan 9 9p remote fs protocol. | ||
49 | vfat.txt | 87 | vfat.txt |
50 | - info on using the VFAT filesystem used in Windows NT and Windows 95 | 88 | - info on using the VFAT filesystem used in Windows NT and Windows 95 |
51 | vfs.txt | 89 | vfs.txt |
52 | - Overview of the Virtual File System | 90 | - overview of the Virtual File System |
53 | xfs.txt | 91 | xfs.txt |
54 | - info and mount options for the XFS filesystem. | 92 | - info and mount options for the XFS filesystem. |
93 | xip.txt | ||
94 | - info on execute-in-place for file mappings. | ||
diff --git a/Documentation/ioctl-number.txt b/Documentation/ioctl-number.txt index aa7ba00ec082..171a44ebd939 100644 --- a/Documentation/ioctl-number.txt +++ b/Documentation/ioctl-number.txt | |||
@@ -78,8 +78,6 @@ Code Seq# Include File Comments | |||
78 | '#' 00-3F IEEE 1394 Subsystem Block for the entire subsystem | 78 | '#' 00-3F IEEE 1394 Subsystem Block for the entire subsystem |
79 | '1' 00-1F <linux/timepps.h> PPS kit from Ulrich Windl | 79 | '1' 00-1F <linux/timepps.h> PPS kit from Ulrich Windl |
80 | <ftp://ftp.de.kernel.org/pub/linux/daemons/ntp/PPS/> | 80 | <ftp://ftp.de.kernel.org/pub/linux/daemons/ntp/PPS/> |
81 | '6' 00-10 <asm-i386/processor.h> Intel IA32 microcode update driver | ||
82 | <mailto:tigran@veritas.com> | ||
83 | '8' all SNP8023 advanced NIC card | 81 | '8' all SNP8023 advanced NIC card |
84 | <mailto:mcr@solidum.com> | 82 | <mailto:mcr@solidum.com> |
85 | 'A' 00-1F linux/apm_bios.h | 83 | 'A' 00-1F linux/apm_bios.h |
diff --git a/Documentation/m68k/README.buddha b/Documentation/m68k/README.buddha index bf802ffc98ad..ef484a719bb9 100644 --- a/Documentation/m68k/README.buddha +++ b/Documentation/m68k/README.buddha | |||
@@ -29,7 +29,7 @@ address is written to $4a, then the whole Byte is written to | |||
29 | $48, while it doesn't matter how often you're writing to $4a | 29 | $48, while it doesn't matter how often you're writing to $4a |
30 | as long as $48 is not touched. After $48 has been written, | 30 | as long as $48 is not touched. After $48 has been written, |
31 | the whole card disappears from $e8 and is mapped to the new | 31 | the whole card disappears from $e8 and is mapped to the new |
32 | address just written. Make shure $4a is written before $48, | 32 | address just written. Make sure $4a is written before $48, |
33 | otherwise your chance is only 1:16 to find the board :-). | 33 | otherwise your chance is only 1:16 to find the board :-). |
34 | 34 | ||
35 | The local memory-map is even active when mapped to $e8: | 35 | The local memory-map is even active when mapped to $e8: |
diff --git a/Documentation/networking/ifenslave.c b/Documentation/networking/ifenslave.c index 545447ac503a..a12059886755 100644 --- a/Documentation/networking/ifenslave.c +++ b/Documentation/networking/ifenslave.c | |||
@@ -87,7 +87,7 @@ | |||
87 | * would fail and generate an error message in the system log. | 87 | * would fail and generate an error message in the system log. |
88 | * - For opt_c: slave should not be set to the master's setting | 88 | * - For opt_c: slave should not be set to the master's setting |
89 | * while it is running. It was already set during enslave. To | 89 | * while it is running. It was already set during enslave. To |
90 | * simplify things, it is now handeled separately. | 90 | * simplify things, it is now handled separately. |
91 | * | 91 | * |
92 | * - 2003/12/01 - Shmulik Hen <shmulik.hen at intel dot com> | 92 | * - 2003/12/01 - Shmulik Hen <shmulik.hen at intel dot com> |
93 | * - Code cleanup and style changes | 93 | * - Code cleanup and style changes |
diff --git a/Documentation/networking/vortex.txt b/Documentation/networking/vortex.txt index 3759acf95b29..6091e5f6794f 100644 --- a/Documentation/networking/vortex.txt +++ b/Documentation/networking/vortex.txt | |||
@@ -24,36 +24,44 @@ Since kernel 2.3.99-pre6, this driver incorporates the support for the | |||
24 | 24 | ||
25 | This driver supports the following hardware: | 25 | This driver supports the following hardware: |
26 | 26 | ||
27 | 3c590 Vortex 10Mbps | 27 | 3c590 Vortex 10Mbps |
28 | 3c592 EISA 10mbps Demon/Vortex | 28 | 3c592 EISA 10Mbps Demon/Vortex |
29 | 3c597 EISA Fast Demon/Vortex | 29 | 3c597 EISA Fast Demon/Vortex |
30 | 3c595 Vortex 100baseTx | 30 | 3c595 Vortex 100baseTx |
31 | 3c595 Vortex 100baseT4 | 31 | 3c595 Vortex 100baseT4 |
32 | 3c595 Vortex 100base-MII | 32 | 3c595 Vortex 100base-MII |
33 | 3Com Vortex | 33 | 3c900 Boomerang 10baseT |
34 | 3c900 Boomerang 10baseT | 34 | 3c900 Boomerang 10Mbps Combo |
35 | 3c900 Boomerang 10Mbps Combo | 35 | 3c900 Cyclone 10Mbps TPO |
36 | 3c900 Cyclone 10Mbps TPO | 36 | 3c900 Cyclone 10Mbps Combo |
37 | 3c900B Cyclone 10Mbps T | 37 | 3c900 Cyclone 10Mbps TPC |
38 | 3c900 Cyclone 10Mbps Combo | 38 | 3c900B-FL Cyclone 10base-FL |
39 | 3c900 Cyclone 10Mbps TPC | 39 | 3c905 Boomerang 100baseTx |
40 | 3c900B-FL Cyclone 10base-FL | 40 | 3c905 Boomerang 100baseT4 |
41 | 3c905 Boomerang 100baseTx | 41 | 3c905B Cyclone 100baseTx |
42 | 3c905 Boomerang 100baseT4 | 42 | 3c905B Cyclone 10/100/BNC |
43 | 3c905B Cyclone 100baseTx | 43 | 3c905B-FX Cyclone 100baseFx |
44 | 3c905B Cyclone 10/100/BNC | 44 | 3c905C Tornado |
45 | 3c905B-FX Cyclone 100baseFx | 45 | 3c920B-EMB-WNM (ATI Radeon 9100 IGP) |
46 | 3c905C Tornado | 46 | 3c980 Cyclone |
47 | 3c980 Cyclone | 47 | 3c980C Python-T |
48 | 3cSOHO100-TX Hurricane | 48 | 3cSOHO100-TX Hurricane |
49 | 3c555 Laptop Hurricane | 49 | 3c555 Laptop Hurricane |
50 | 3c575 Boomerang CardBus | 50 | 3c556 Laptop Tornado |
51 | 3CCFE575 Cyclone CardBus | 51 | 3c556B Laptop Hurricane |
52 | 3CCFE575CT Cyclone CardBus | 52 | 3c575 [Megahertz] 10/100 LAN CardBus |
53 | 3CCFE656 Cyclone CardBus | 53 | 3c575 Boomerang CardBus |
54 | 3CCFEM656 Cyclone CardBus | 54 | 3CCFE575BT Cyclone CardBus |
55 | 3c450 Cyclone/unknown | 55 | 3CCFE575CT Tornado CardBus |
56 | 56 | 3CCFE656 Cyclone CardBus | |
57 | 3CCFEM656B Cyclone+Winmodem CardBus | ||
58 | 3CXFEM656C Tornado+Winmodem CardBus | ||
59 | 3c450 HomePNA Tornado | ||
60 | 3c920 Tornado | ||
61 | 3c982 Hydra Dual Port A | ||
62 | 3c982 Hydra Dual Port B | ||
63 | 3c905B-T4 | ||
64 | 3c920B-EMB-WNM Tornado | ||
57 | 65 | ||
58 | Module parameters | 66 | Module parameters |
59 | ================= | 67 | ================= |
@@ -293,11 +301,6 @@ Donald's wake-on-LAN page: | |||
293 | 301 | ||
294 | http://www.scyld.com/wakeonlan.html | 302 | http://www.scyld.com/wakeonlan.html |
295 | 303 | ||
296 | 3Com's documentation for many NICs, including the ones supported by | ||
297 | this driver is available at | ||
298 | |||
299 | http://support.3com.com/partners/developer/developer_form.html | ||
300 | |||
301 | 3Com's DOS-based application for setting up the NICs EEPROMs: | 304 | 3Com's DOS-based application for setting up the NICs EEPROMs: |
302 | 305 | ||
303 | ftp://ftp.3com.com/pub/nic/3c90x/3c90xx2.exe | 306 | ftp://ftp.3com.com/pub/nic/3c90x/3c90xx2.exe |
@@ -312,10 +315,10 @@ Autonegotiation notes | |||
312 | --------------------- | 315 | --------------------- |
313 | 316 | ||
314 | The driver uses a one-minute heartbeat for adapting to changes in | 317 | The driver uses a one-minute heartbeat for adapting to changes in |
315 | the external LAN environment. This means that when, for example, a | 318 | the external LAN environment if link is up and 5 seconds if link is down. |
316 | machine is unplugged from a hubbed 10baseT LAN plugged into a | 319 | This means that when, for example, a machine is unplugged from a hubbed |
317 | switched 100baseT LAN, the throughput will be quite dreadful for up | 320 | 10baseT LAN plugged into a switched 100baseT LAN, the throughput |
318 | to sixty seconds. Be patient. | 321 | will be quite dreadful for up to sixty seconds. Be patient. |
319 | 322 | ||
320 | Cisco interoperability note from Walter Wong <wcw+@CMU.EDU>: | 323 | Cisco interoperability note from Walter Wong <wcw+@CMU.EDU>: |
321 | 324 | ||
diff --git a/Documentation/pnp.txt b/Documentation/pnp.txt index af0f6eabfa1c..9529c9c9fd59 100644 --- a/Documentation/pnp.txt +++ b/Documentation/pnp.txt | |||
@@ -115,6 +115,9 @@ pnp_unregister_protocol | |||
115 | pnp_register_driver | 115 | pnp_register_driver |
116 | - adds a PnP driver to the Plug and Play Layer | 116 | - adds a PnP driver to the Plug and Play Layer |
117 | - this includes driver model integration | 117 | - this includes driver model integration |
118 | - returns zero for success or a negative error number for failure; count | ||
119 | calls to the .add() method if you need to know how many devices bind to | ||
120 | the driver | ||
118 | 121 | ||
119 | pnp_unregister_driver | 122 | pnp_unregister_driver |
120 | - removes a PnP driver from the Plug and Play Layer | 123 | - removes a PnP driver from the Plug and Play Layer |
diff --git a/Documentation/robust-futex-ABI.txt b/Documentation/robust-futex-ABI.txt new file mode 100644 index 000000000000..8529a17ffaa1 --- /dev/null +++ b/Documentation/robust-futex-ABI.txt | |||
@@ -0,0 +1,182 @@ | |||
1 | Started by Paul Jackson <pj@sgi.com> | ||
2 | |||
3 | The robust futex ABI | ||
4 | -------------------- | ||
5 | |||
6 | Robust_futexes provide a mechanism that is used in addition to normal | ||
7 | futexes, for kernel assist of cleanup of held locks on task exit. | ||
8 | |||
9 | The interesting data as to what futexes a thread is holding is kept on a | ||
10 | linked list in user space, where it can be updated efficiently as locks | ||
11 | are taken and dropped, without kernel intervention. The only additional | ||
12 | kernel intervention required for robust_futexes above and beyond what is | ||
13 | required for futexes is: | ||
14 | |||
15 | 1) a one time call, per thread, to tell the kernel where its list of | ||
16 | held robust_futexes begins, and | ||
17 | 2) internal kernel code at exit, to handle any listed locks held | ||
18 | by the exiting thread. | ||
19 | |||
20 | The existing normal futexes already provide a "Fast Userspace Locking" | ||
21 | mechanism, which handles uncontested locking without needing a system | ||
22 | call, and handles contested locking by maintaining a list of waiting | ||
23 | threads in the kernel. Options on the sys_futex(2) system call support | ||
24 | waiting on a particular futex, and waking up the next waiter on a | ||
25 | particular futex. | ||
26 | |||
27 | For robust_futexes to work, the user code (typically in a library such | ||
28 | as glibc linked with the application) has to manage and place the | ||
29 | necessary list elements exactly as the kernel expects them. If it fails | ||
30 | to do so, then improperly listed locks will not be cleaned up on exit, | ||
31 | probably causing deadlock or other such failure of the other threads | ||
32 | waiting on the same locks. | ||
33 | |||
34 | A thread that anticipates possibly using robust_futexes should first | ||
35 | issue the system call: | ||
36 | |||
37 | asmlinkage long | ||
38 | sys_set_robust_list(struct robust_list_head __user *head, size_t len); | ||
39 | |||
40 | The pointer 'head' points to a structure in the threads address space | ||
41 | consisting of three words. Each word is 32 bits on 32 bit arch's, or 64 | ||
42 | bits on 64 bit arch's, and local byte order. Each thread should have | ||
43 | its own thread private 'head'. | ||
44 | |||
45 | If a thread is running in 32 bit compatibility mode on a 64 native arch | ||
46 | kernel, then it can actually have two such structures - one using 32 bit | ||
47 | words for 32 bit compatibility mode, and one using 64 bit words for 64 | ||
48 | bit native mode. The kernel, if it is a 64 bit kernel supporting 32 bit | ||
49 | compatibility mode, will attempt to process both lists on each task | ||
50 | exit, if the corresponding sys_set_robust_list() call has been made to | ||
51 | setup that list. | ||
52 | |||
53 | The first word in the memory structure at 'head' contains a | ||
54 | pointer to a single linked list of 'lock entries', one per lock, | ||
55 | as described below. If the list is empty, the pointer will point | ||
56 | to itself, 'head'. The last 'lock entry' points back to the 'head'. | ||
57 | |||
58 | The second word, called 'offset', specifies the offset from the | ||
59 | address of the associated 'lock entry', plus or minus, of what will | ||
60 | be called the 'lock word', from that 'lock entry'. The 'lock word' | ||
61 | is always a 32 bit word, unlike the other words above. The 'lock | ||
62 | word' holds 3 flag bits in the upper 3 bits, and the thread id (TID) | ||
63 | of the thread holding the lock in the bottom 29 bits. See further | ||
64 | below for a description of the flag bits. | ||
65 | |||
66 | The third word, called 'list_op_pending', contains transient copy of | ||
67 | the address of the 'lock entry', during list insertion and removal, | ||
68 | and is needed to correctly resolve races should a thread exit while | ||
69 | in the middle of a locking or unlocking operation. | ||
70 | |||
71 | Each 'lock entry' on the single linked list starting at 'head' consists | ||
72 | of just a single word, pointing to the next 'lock entry', or back to | ||
73 | 'head' if there are no more entries. In addition, nearby to each 'lock | ||
74 | entry', at an offset from the 'lock entry' specified by the 'offset' | ||
75 | word, is one 'lock word'. | ||
76 | |||
77 | The 'lock word' is always 32 bits, and is intended to be the same 32 bit | ||
78 | lock variable used by the futex mechanism, in conjunction with | ||
79 | robust_futexes. The kernel will only be able to wakeup the next thread | ||
80 | waiting for a lock on a threads exit if that next thread used the futex | ||
81 | mechanism to register the address of that 'lock word' with the kernel. | ||
82 | |||
83 | For each futex lock currently held by a thread, if it wants this | ||
84 | robust_futex support for exit cleanup of that lock, it should have one | ||
85 | 'lock entry' on this list, with its associated 'lock word' at the | ||
86 | specified 'offset'. Should a thread die while holding any such locks, | ||
87 | the kernel will walk this list, mark any such locks with a bit | ||
88 | indicating their holder died, and wakeup the next thread waiting for | ||
89 | that lock using the futex mechanism. | ||
90 | |||
91 | When a thread has invoked the above system call to indicate it | ||
92 | anticipates using robust_futexes, the kernel stores the passed in 'head' | ||
93 | pointer for that task. The task may retrieve that value later on by | ||
94 | using the system call: | ||
95 | |||
96 | asmlinkage long | ||
97 | sys_get_robust_list(int pid, struct robust_list_head __user **head_ptr, | ||
98 | size_t __user *len_ptr); | ||
99 | |||
100 | It is anticipated that threads will use robust_futexes embedded in | ||
101 | larger, user level locking structures, one per lock. The kernel | ||
102 | robust_futex mechanism doesn't care what else is in that structure, so | ||
103 | long as the 'offset' to the 'lock word' is the same for all | ||
104 | robust_futexes used by that thread. The thread should link those locks | ||
105 | it currently holds using the 'lock entry' pointers. It may also have | ||
106 | other links between the locks, such as the reverse side of a double | ||
107 | linked list, but that doesn't matter to the kernel. | ||
108 | |||
109 | By keeping its locks linked this way, on a list starting with a 'head' | ||
110 | pointer known to the kernel, the kernel can provide to a thread the | ||
111 | essential service available for robust_futexes, which is to help clean | ||
112 | up locks held at the time of (a perhaps unexpectedly) exit. | ||
113 | |||
114 | Actual locking and unlocking, during normal operations, is handled | ||
115 | entirely by user level code in the contending threads, and by the | ||
116 | existing futex mechanism to wait for, and wakeup, locks. The kernels | ||
117 | only essential involvement in robust_futexes is to remember where the | ||
118 | list 'head' is, and to walk the list on thread exit, handling locks | ||
119 | still held by the departing thread, as described below. | ||
120 | |||
121 | There may exist thousands of futex lock structures in a threads shared | ||
122 | memory, on various data structures, at a given point in time. Only those | ||
123 | lock structures for locks currently held by that thread should be on | ||
124 | that thread's robust_futex linked lock list a given time. | ||
125 | |||
126 | A given futex lock structure in a user shared memory region may be held | ||
127 | at different times by any of the threads with access to that region. The | ||
128 | thread currently holding such a lock, if any, is marked with the threads | ||
129 | TID in the lower 29 bits of the 'lock word'. | ||
130 | |||
131 | When adding or removing a lock from its list of held locks, in order for | ||
132 | the kernel to correctly handle lock cleanup regardless of when the task | ||
133 | exits (perhaps it gets an unexpected signal 9 in the middle of | ||
134 | manipulating this list), the user code must observe the following | ||
135 | protocol on 'lock entry' insertion and removal: | ||
136 | |||
137 | On insertion: | ||
138 | 1) set the 'list_op_pending' word to the address of the 'lock word' | ||
139 | to be inserted, | ||
140 | 2) acquire the futex lock, | ||
141 | 3) add the lock entry, with its thread id (TID) in the bottom 29 bits | ||
142 | of the 'lock word', to the linked list starting at 'head', and | ||
143 | 4) clear the 'list_op_pending' word. | ||
144 | |||
145 | On removal: | ||
146 | 1) set the 'list_op_pending' word to the address of the 'lock word' | ||
147 | to be removed, | ||
148 | 2) remove the lock entry for this lock from the 'head' list, | ||
149 | 2) release the futex lock, and | ||
150 | 2) clear the 'lock_op_pending' word. | ||
151 | |||
152 | On exit, the kernel will consider the address stored in | ||
153 | 'list_op_pending' and the address of each 'lock word' found by walking | ||
154 | the list starting at 'head'. For each such address, if the bottom 29 | ||
155 | bits of the 'lock word' at offset 'offset' from that address equals the | ||
156 | exiting threads TID, then the kernel will do two things: | ||
157 | |||
158 | 1) if bit 31 (0x80000000) is set in that word, then attempt a futex | ||
159 | wakeup on that address, which will waken the next thread that has | ||
160 | used to the futex mechanism to wait on that address, and | ||
161 | 2) atomically set bit 30 (0x40000000) in the 'lock word'. | ||
162 | |||
163 | In the above, bit 31 was set by futex waiters on that lock to indicate | ||
164 | they were waiting, and bit 30 is set by the kernel to indicate that the | ||
165 | lock owner died holding the lock. | ||
166 | |||
167 | The kernel exit code will silently stop scanning the list further if at | ||
168 | any point: | ||
169 | |||
170 | 1) the 'head' pointer or an subsequent linked list pointer | ||
171 | is not a valid address of a user space word | ||
172 | 2) the calculated location of the 'lock word' (address plus | ||
173 | 'offset') is not the valud address of a 32 bit user space | ||
174 | word | ||
175 | 3) if the list contains more than 1 million (subject to | ||
176 | future kernel configuration changes) elements. | ||
177 | |||
178 | When the kernel sees a list entry whose 'lock word' doesn't have the | ||
179 | current threads TID in the lower 29 bits, it does nothing with that | ||
180 | entry, and goes on to the next entry. | ||
181 | |||
182 | Bit 29 (0x20000000) of the 'lock word' is reserved for future use. | ||
diff --git a/Documentation/robust-futexes.txt b/Documentation/robust-futexes.txt new file mode 100644 index 000000000000..df82d75245a0 --- /dev/null +++ b/Documentation/robust-futexes.txt | |||
@@ -0,0 +1,218 @@ | |||
1 | Started by: Ingo Molnar <mingo@redhat.com> | ||
2 | |||
3 | Background | ||
4 | ---------- | ||
5 | |||
6 | what are robust futexes? To answer that, we first need to understand | ||
7 | what futexes are: normal futexes are special types of locks that in the | ||
8 | noncontended case can be acquired/released from userspace without having | ||
9 | to enter the kernel. | ||
10 | |||
11 | A futex is in essence a user-space address, e.g. a 32-bit lock variable | ||
12 | field. If userspace notices contention (the lock is already owned and | ||
13 | someone else wants to grab it too) then the lock is marked with a value | ||
14 | that says "there's a waiter pending", and the sys_futex(FUTEX_WAIT) | ||
15 | syscall is used to wait for the other guy to release it. The kernel | ||
16 | creates a 'futex queue' internally, so that it can later on match up the | ||
17 | waiter with the waker - without them having to know about each other. | ||
18 | When the owner thread releases the futex, it notices (via the variable | ||
19 | value) that there were waiter(s) pending, and does the | ||
20 | sys_futex(FUTEX_WAKE) syscall to wake them up. Once all waiters have | ||
21 | taken and released the lock, the futex is again back to 'uncontended' | ||
22 | state, and there's no in-kernel state associated with it. The kernel | ||
23 | completely forgets that there ever was a futex at that address. This | ||
24 | method makes futexes very lightweight and scalable. | ||
25 | |||
26 | "Robustness" is about dealing with crashes while holding a lock: if a | ||
27 | process exits prematurely while holding a pthread_mutex_t lock that is | ||
28 | also shared with some other process (e.g. yum segfaults while holding a | ||
29 | pthread_mutex_t, or yum is kill -9-ed), then waiters for that lock need | ||
30 | to be notified that the last owner of the lock exited in some irregular | ||
31 | way. | ||
32 | |||
33 | To solve such types of problems, "robust mutex" userspace APIs were | ||
34 | created: pthread_mutex_lock() returns an error value if the owner exits | ||
35 | prematurely - and the new owner can decide whether the data protected by | ||
36 | the lock can be recovered safely. | ||
37 | |||
38 | There is a big conceptual problem with futex based mutexes though: it is | ||
39 | the kernel that destroys the owner task (e.g. due to a SEGFAULT), but | ||
40 | the kernel cannot help with the cleanup: if there is no 'futex queue' | ||
41 | (and in most cases there is none, futexes being fast lightweight locks) | ||
42 | then the kernel has no information to clean up after the held lock! | ||
43 | Userspace has no chance to clean up after the lock either - userspace is | ||
44 | the one that crashes, so it has no opportunity to clean up. Catch-22. | ||
45 | |||
46 | In practice, when e.g. yum is kill -9-ed (or segfaults), a system reboot | ||
47 | is needed to release that futex based lock. This is one of the leading | ||
48 | bugreports against yum. | ||
49 | |||
50 | To solve this problem, the traditional approach was to extend the vma | ||
51 | (virtual memory area descriptor) concept to have a notion of 'pending | ||
52 | robust futexes attached to this area'. This approach requires 3 new | ||
53 | syscall variants to sys_futex(): FUTEX_REGISTER, FUTEX_DEREGISTER and | ||
54 | FUTEX_RECOVER. At do_exit() time, all vmas are searched to see whether | ||
55 | they have a robust_head set. This approach has two fundamental problems | ||
56 | left: | ||
57 | |||
58 | - it has quite complex locking and race scenarios. The vma-based | ||
59 | approach had been pending for years, but they are still not completely | ||
60 | reliable. | ||
61 | |||
62 | - they have to scan _every_ vma at sys_exit() time, per thread! | ||
63 | |||
64 | The second disadvantage is a real killer: pthread_exit() takes around 1 | ||
65 | microsecond on Linux, but with thousands (or tens of thousands) of vmas | ||
66 | every pthread_exit() takes a millisecond or more, also totally | ||
67 | destroying the CPU's L1 and L2 caches! | ||
68 | |||
69 | This is very much noticeable even for normal process sys_exit_group() | ||
70 | calls: the kernel has to do the vma scanning unconditionally! (this is | ||
71 | because the kernel has no knowledge about how many robust futexes there | ||
72 | are to be cleaned up, because a robust futex might have been registered | ||
73 | in another task, and the futex variable might have been simply mmap()-ed | ||
74 | into this process's address space). | ||
75 | |||
76 | This huge overhead forced the creation of CONFIG_FUTEX_ROBUST so that | ||
77 | normal kernels can turn it off, but worse than that: the overhead makes | ||
78 | robust futexes impractical for any type of generic Linux distribution. | ||
79 | |||
80 | So something had to be done. | ||
81 | |||
82 | New approach to robust futexes | ||
83 | ------------------------------ | ||
84 | |||
85 | At the heart of this new approach there is a per-thread private list of | ||
86 | robust locks that userspace is holding (maintained by glibc) - which | ||
87 | userspace list is registered with the kernel via a new syscall [this | ||
88 | registration happens at most once per thread lifetime]. At do_exit() | ||
89 | time, the kernel checks this user-space list: are there any robust futex | ||
90 | locks to be cleaned up? | ||
91 | |||
92 | In the common case, at do_exit() time, there is no list registered, so | ||
93 | the cost of robust futexes is just a simple current->robust_list != NULL | ||
94 | comparison. If the thread has registered a list, then normally the list | ||
95 | is empty. If the thread/process crashed or terminated in some incorrect | ||
96 | way then the list might be non-empty: in this case the kernel carefully | ||
97 | walks the list [not trusting it], and marks all locks that are owned by | ||
98 | this thread with the FUTEX_OWNER_DEAD bit, and wakes up one waiter (if | ||
99 | any). | ||
100 | |||
101 | The list is guaranteed to be private and per-thread at do_exit() time, | ||
102 | so it can be accessed by the kernel in a lockless way. | ||
103 | |||
104 | There is one race possible though: since adding to and removing from the | ||
105 | list is done after the futex is acquired by glibc, there is a few | ||
106 | instructions window for the thread (or process) to die there, leaving | ||
107 | the futex hung. To protect against this possibility, userspace (glibc) | ||
108 | also maintains a simple per-thread 'list_op_pending' field, to allow the | ||
109 | kernel to clean up if the thread dies after acquiring the lock, but just | ||
110 | before it could have added itself to the list. Glibc sets this | ||
111 | list_op_pending field before it tries to acquire the futex, and clears | ||
112 | it after the list-add (or list-remove) has finished. | ||
113 | |||
114 | That's all that is needed - all the rest of robust-futex cleanup is done | ||
115 | in userspace [just like with the previous patches]. | ||
116 | |||
117 | Ulrich Drepper has implemented the necessary glibc support for this new | ||
118 | mechanism, which fully enables robust mutexes. | ||
119 | |||
120 | Key differences of this userspace-list based approach, compared to the | ||
121 | vma based method: | ||
122 | |||
123 | - it's much, much faster: at thread exit time, there's no need to loop | ||
124 | over every vma (!), which the VM-based method has to do. Only a very | ||
125 | simple 'is the list empty' op is done. | ||
126 | |||
127 | - no VM changes are needed - 'struct address_space' is left alone. | ||
128 | |||
129 | - no registration of individual locks is needed: robust mutexes dont | ||
130 | need any extra per-lock syscalls. Robust mutexes thus become a very | ||
131 | lightweight primitive - so they dont force the application designer | ||
132 | to do a hard choice between performance and robustness - robust | ||
133 | mutexes are just as fast. | ||
134 | |||
135 | - no per-lock kernel allocation happens. | ||
136 | |||
137 | - no resource limits are needed. | ||
138 | |||
139 | - no kernel-space recovery call (FUTEX_RECOVER) is needed. | ||
140 | |||
141 | - the implementation and the locking is "obvious", and there are no | ||
142 | interactions with the VM. | ||
143 | |||
144 | Performance | ||
145 | ----------- | ||
146 | |||
147 | I have benchmarked the time needed for the kernel to process a list of 1 | ||
148 | million (!) held locks, using the new method [on a 2GHz CPU]: | ||
149 | |||
150 | - with FUTEX_WAIT set [contended mutex]: 130 msecs | ||
151 | - without FUTEX_WAIT set [uncontended mutex]: 30 msecs | ||
152 | |||
153 | I have also measured an approach where glibc does the lock notification | ||
154 | [which it currently does for !pshared robust mutexes], and that took 256 | ||
155 | msecs - clearly slower, due to the 1 million FUTEX_WAKE syscalls | ||
156 | userspace had to do. | ||
157 | |||
158 | (1 million held locks are unheard of - we expect at most a handful of | ||
159 | locks to be held at a time. Nevertheless it's nice to know that this | ||
160 | approach scales nicely.) | ||
161 | |||
162 | Implementation details | ||
163 | ---------------------- | ||
164 | |||
165 | The patch adds two new syscalls: one to register the userspace list, and | ||
166 | one to query the registered list pointer: | ||
167 | |||
168 | asmlinkage long | ||
169 | sys_set_robust_list(struct robust_list_head __user *head, | ||
170 | size_t len); | ||
171 | |||
172 | asmlinkage long | ||
173 | sys_get_robust_list(int pid, struct robust_list_head __user **head_ptr, | ||
174 | size_t __user *len_ptr); | ||
175 | |||
176 | List registration is very fast: the pointer is simply stored in | ||
177 | current->robust_list. [Note that in the future, if robust futexes become | ||
178 | widespread, we could extend sys_clone() to register a robust-list head | ||
179 | for new threads, without the need of another syscall.] | ||
180 | |||
181 | So there is virtually zero overhead for tasks not using robust futexes, | ||
182 | and even for robust futex users, there is only one extra syscall per | ||
183 | thread lifetime, and the cleanup operation, if it happens, is fast and | ||
184 | straightforward. The kernel doesnt have any internal distinction between | ||
185 | robust and normal futexes. | ||
186 | |||
187 | If a futex is found to be held at exit time, the kernel sets the | ||
188 | following bit of the futex word: | ||
189 | |||
190 | #define FUTEX_OWNER_DIED 0x40000000 | ||
191 | |||
192 | and wakes up the next futex waiter (if any). User-space does the rest of | ||
193 | the cleanup. | ||
194 | |||
195 | Otherwise, robust futexes are acquired by glibc by putting the TID into | ||
196 | the futex field atomically. Waiters set the FUTEX_WAITERS bit: | ||
197 | |||
198 | #define FUTEX_WAITERS 0x80000000 | ||
199 | |||
200 | and the remaining bits are for the TID. | ||
201 | |||
202 | Testing, architecture support | ||
203 | ----------------------------- | ||
204 | |||
205 | i've tested the new syscalls on x86 and x86_64, and have made sure the | ||
206 | parsing of the userspace list is robust [ ;-) ] even if the list is | ||
207 | deliberately corrupted. | ||
208 | |||
209 | i386 and x86_64 syscalls are wired up at the moment, and Ulrich has | ||
210 | tested the new glibc code (on x86_64 and i386), and it works for his | ||
211 | robust-mutex testcases. | ||
212 | |||
213 | All other architectures should build just fine too - but they wont have | ||
214 | the new syscalls yet. | ||
215 | |||
216 | Architectures need to implement the new futex_atomic_cmpxchg_inatomic() | ||
217 | inline function before writing up the syscalls (that function returns | ||
218 | -ENOSYS right now). | ||
diff --git a/Documentation/rpc-cache.txt b/Documentation/rpc-cache.txt index 2b5d4434fa5a..5f757c8cf979 100644 --- a/Documentation/rpc-cache.txt +++ b/Documentation/rpc-cache.txt | |||
@@ -1,4 +1,4 @@ | |||
1 | This document gives a brief introduction to the caching | 1 | This document gives a brief introduction to the caching |
2 | mechanisms in the sunrpc layer that is used, in particular, | 2 | mechanisms in the sunrpc layer that is used, in particular, |
3 | for NFS authentication. | 3 | for NFS authentication. |
4 | 4 | ||
@@ -25,25 +25,17 @@ The common code handles such things as: | |||
25 | - supporting 'NEGATIVE' as well as positive entries | 25 | - supporting 'NEGATIVE' as well as positive entries |
26 | - allowing an EXPIRED time on cache items, and removing | 26 | - allowing an EXPIRED time on cache items, and removing |
27 | items after they expire, and are no longe in-use. | 27 | items after they expire, and are no longe in-use. |
28 | |||
29 | Future code extensions are expect to handle | ||
30 | - making requests to user-space to fill in cache entries | 28 | - making requests to user-space to fill in cache entries |
31 | - allowing user-space to directly set entries in the cache | 29 | - allowing user-space to directly set entries in the cache |
32 | - delaying RPC requests that depend on as-yet incomplete | 30 | - delaying RPC requests that depend on as-yet incomplete |
33 | cache entries, and replaying those requests when the cache entry | 31 | cache entries, and replaying those requests when the cache entry |
34 | is complete. | 32 | is complete. |
35 | - maintaining last-access times on cache entries | 33 | - clean out old entries as they expire. |
36 | - clean out old entries when the caches become full | ||
37 | |||
38 | The code for performing a cache lookup is also common, but in the form | ||
39 | of a template. i.e. a #define. | ||
40 | Each cache defines a lookup function by using the DefineCacheLookup | ||
41 | macro, or the simpler DefineSimpleCacheLookup macro | ||
42 | 34 | ||
43 | Creating a Cache | 35 | Creating a Cache |
44 | ---------------- | 36 | ---------------- |
45 | 37 | ||
46 | 1/ A cache needs a datum to cache. This is in the form of a | 38 | 1/ A cache needs a datum to store. This is in the form of a |
47 | structure definition that must contain a | 39 | structure definition that must contain a |
48 | struct cache_head | 40 | struct cache_head |
49 | as an element, usually the first. | 41 | as an element, usually the first. |
@@ -51,35 +43,69 @@ Creating a Cache | |||
51 | Each cache element is reference counted and contains | 43 | Each cache element is reference counted and contains |
52 | expiry and update times for use in cache management. | 44 | expiry and update times for use in cache management. |
53 | 2/ A cache needs a "cache_detail" structure that | 45 | 2/ A cache needs a "cache_detail" structure that |
54 | describes the cache. This stores the hash table, and some | 46 | describes the cache. This stores the hash table, some |
55 | parameters for cache management. | 47 | parameters for cache management, and some operations detailing how |
56 | 3/ A cache needs a lookup function. This is created using | 48 | to work with particular cache items. |
57 | the DefineCacheLookup macro. This lookup function is used both | 49 | The operations requires are: |
58 | to find entries and to update entries. The normal mode for | 50 | struct cache_head *alloc(void) |
59 | updating an entry is to replace the old entry with a new | 51 | This simply allocates appropriate memory and returns |
60 | entry. However it is possible to allow update-in-place | 52 | a pointer to the cache_detail embedded within the |
61 | for those caches where it makes sense (no atomicity issues | 53 | structure |
62 | or indirect reference counting issue) | 54 | void cache_put(struct kref *) |
63 | 4/ A cache needs to be registered using cache_register(). This | 55 | This is called when the last reference to an item is |
64 | includes in on a list of caches that will be regularly | 56 | is dropped. The pointer passed is to the 'ref' field |
65 | cleaned to discard old data. For this to work, some | 57 | in the cache_head. cache_put should release any |
66 | thread must periodically call cache_clean | 58 | references create by 'cache_init' and, if CACHE_VALID |
67 | 59 | is set, any references created by cache_update. | |
60 | It should then release the memory allocated by | ||
61 | 'alloc'. | ||
62 | int match(struct cache_head *orig, struct cache_head *new) | ||
63 | test if the keys in the two structures match. Return | ||
64 | 1 if they do, 0 if they don't. | ||
65 | void init(struct cache_head *orig, struct cache_head *new) | ||
66 | Set the 'key' fields in 'new' from 'orig'. This may | ||
67 | include taking references to shared objects. | ||
68 | void update(struct cache_head *orig, struct cache_head *new) | ||
69 | Set the 'content' fileds in 'new' from 'orig'. | ||
70 | int cache_show(struct seq_file *m, struct cache_detail *cd, | ||
71 | struct cache_head *h) | ||
72 | Optional. Used to provide a /proc file that lists the | ||
73 | contents of a cache. This should show one item, | ||
74 | usually on just one line. | ||
75 | int cache_request(struct cache_detail *cd, struct cache_head *h, | ||
76 | char **bpp, int *blen) | ||
77 | Format a request to be send to user-space for an item | ||
78 | to be instantiated. *bpp is a buffer of size *blen. | ||
79 | bpp should be moved forward over the encoded message, | ||
80 | and *blen should be reduced to show how much free | ||
81 | space remains. Return 0 on success or <0 if not | ||
82 | enough room or other problem. | ||
83 | int cache_parse(struct cache_detail *cd, char *buf, int len) | ||
84 | A message from user space has arrived to fill out a | ||
85 | cache entry. It is in 'buf' of length 'len'. | ||
86 | cache_parse should parse this, find the item in the | ||
87 | cache with sunrpc_cache_lookup, and update the item | ||
88 | with sunrpc_cache_update. | ||
89 | |||
90 | |||
91 | 3/ A cache needs to be registered using cache_register(). This | ||
92 | includes it on a list of caches that will be regularly | ||
93 | cleaned to discard old data. | ||
94 | |||
68 | Using a cache | 95 | Using a cache |
69 | ------------- | 96 | ------------- |
70 | 97 | ||
71 | To find a value in a cache, call the lookup function passing it a the | 98 | To find a value in a cache, call sunrpc_cache_lookup passing a pointer |
72 | datum which contains key, and possibly content, and a flag saying | 99 | to the cache_head in a sample item with the 'key' fields filled in. |
73 | whether to update the cache with new data from the datum. Depending | 100 | This will be passed to ->match to identify the target entry. If no |
74 | on how the cache lookup function was defined, it may take an extra | 101 | entry is found, a new entry will be create, added to the cache, and |
75 | argument to identify the particular cache in question. | 102 | marked as not containing valid data. |
76 | 103 | ||
77 | Except in cases of kmalloc failure, the lookup function | 104 | The item returned is typically passed to cache_check which will check |
78 | will return a new datum which will store the key and | 105 | if the data is valid, and may initiate an up-call to get fresh data. |
79 | may contain valid content, or may not. | 106 | cache_check will return -ENOENT in the entry is negative or if an up |
80 | This datum is typically passed to cache_check which determines the | 107 | call is needed but not possible, -EAGAIN if an upcall is pending, |
81 | validity of the datum and may later initiate an upcall to fill | 108 | or 0 if the data is valid; |
82 | in the data. | ||
83 | 109 | ||
84 | cache_check can be passed a "struct cache_req *". This structure is | 110 | cache_check can be passed a "struct cache_req *". This structure is |
85 | typically embedded in the actual request and can be used to create a | 111 | typically embedded in the actual request and can be used to create a |
@@ -90,6 +116,13 @@ item does become valid, the deferred copy of the request will be | |||
90 | revisited (->revisit). It is expected that this method will | 116 | revisited (->revisit). It is expected that this method will |
91 | reschedule the request for processing. | 117 | reschedule the request for processing. |
92 | 118 | ||
119 | The value returned by sunrpc_cache_lookup can also be passed to | ||
120 | sunrpc_cache_update to set the content for the item. A second item is | ||
121 | passed which should hold the content. If the item found by _lookup | ||
122 | has valid data, then it is discarded and a new item is created. This | ||
123 | saves any user of an item from worrying about content changing while | ||
124 | it is being inspected. If the item found by _lookup does not contain | ||
125 | valid data, then the content is copied across and CACHE_VALID is set. | ||
93 | 126 | ||
94 | Populating a cache | 127 | Populating a cache |
95 | ------------------ | 128 | ------------------ |
@@ -114,8 +147,8 @@ should be create or updated to have the given content, and the | |||
114 | expiry time should be set on that item. | 147 | expiry time should be set on that item. |
115 | 148 | ||
116 | Reading from a channel is a bit more interesting. When a cache | 149 | Reading from a channel is a bit more interesting. When a cache |
117 | lookup fail, or when it suceeds but finds an entry that may soon | 150 | lookup fails, or when it succeeds but finds an entry that may soon |
118 | expiry, a request is lodged for that cache item to be updated by | 151 | expire, a request is lodged for that cache item to be updated by |
119 | user-space. These requests appear in the channel file. | 152 | user-space. These requests appear in the channel file. |
120 | 153 | ||
121 | Successive reads will return successive requests. | 154 | Successive reads will return successive requests. |
@@ -130,7 +163,7 @@ Thus a user-space helper is likely to: | |||
130 | write a response | 163 | write a response |
131 | loop. | 164 | loop. |
132 | 165 | ||
133 | If it dies and needs to be restarted, any requests that have not be | 166 | If it dies and needs to be restarted, any requests that have not been |
134 | answered will still appear in the file and will be read by the new | 167 | answered will still appear in the file and will be read by the new |
135 | instance of the helper. | 168 | instance of the helper. |
136 | 169 | ||
@@ -142,10 +175,9 @@ Each cache should also define a "cache_request" method which | |||
142 | takes a cache item and encodes a request into the buffer | 175 | takes a cache item and encodes a request into the buffer |
143 | provided. | 176 | provided. |
144 | 177 | ||
145 | |||
146 | Note: If a cache has no active readers on the channel, and has had not | 178 | Note: If a cache has no active readers on the channel, and has had not |
147 | active readers for more than 60 seconds, further requests will not be | 179 | active readers for more than 60 seconds, further requests will not be |
148 | added to the channel but instead all looks that do not find a valid | 180 | added to the channel but instead all lookups that do not find a valid |
149 | entry will fail. This is partly for backward compatibility: The | 181 | entry will fail. This is partly for backward compatibility: The |
150 | previous nfs exports table was deemed to be authoritative and a | 182 | previous nfs exports table was deemed to be authoritative and a |
151 | failed lookup meant a definite 'no'. | 183 | failed lookup meant a definite 'no'. |
@@ -154,18 +186,17 @@ request/response format | |||
154 | ----------------------- | 186 | ----------------------- |
155 | 187 | ||
156 | While each cache is free to use it's own format for requests | 188 | While each cache is free to use it's own format for requests |
157 | and responses over channel, the following is recommended are | 189 | and responses over channel, the following is recommended as |
158 | appropriate and support routines are available to help: | 190 | appropriate and support routines are available to help: |
159 | Each request or response record should be printable ASCII | 191 | Each request or response record should be printable ASCII |
160 | with precisely one newline character which should be at the end. | 192 | with precisely one newline character which should be at the end. |
161 | Fields within the record should be separated by spaces, normally one. | 193 | Fields within the record should be separated by spaces, normally one. |
162 | If spaces, newlines, or nul characters are needed in a field they | 194 | If spaces, newlines, or nul characters are needed in a field they |
163 | much be quotes. two mechanisms are available: | 195 | much be quoted. two mechanisms are available: |
164 | 1/ If a field begins '\x' then it must contain an even number of | 196 | 1/ If a field begins '\x' then it must contain an even number of |
165 | hex digits, and pairs of these digits provide the bytes in the | 197 | hex digits, and pairs of these digits provide the bytes in the |
166 | field. | 198 | field. |
167 | 2/ otherwise a \ in the field must be followed by 3 octal digits | 199 | 2/ otherwise a \ in the field must be followed by 3 octal digits |
168 | which give the code for a byte. Other characters are treated | 200 | which give the code for a byte. Other characters are treated |
169 | as them selves. At the very least, space, newlines nul, and | 201 | as them selves. At the very least, space, newline, nul, and |
170 | '\' must be quoted in this way. | 202 | '\' must be quoted in this way. |
171 | |||
diff --git a/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl b/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl index 6dc9d9f622ca..6feef9e82b63 100644 --- a/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl +++ b/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl | |||
@@ -2836,7 +2836,7 @@ struct _snd_pcm_runtime { | |||
2836 | 2836 | ||
2837 | <para> | 2837 | <para> |
2838 | Note that this callback became non-atomic since the recent version. | 2838 | Note that this callback became non-atomic since the recent version. |
2839 | You can use schedule-related fucntions safely in this callback now. | 2839 | You can use schedule-related functions safely in this callback now. |
2840 | </para> | 2840 | </para> |
2841 | 2841 | ||
2842 | <para> | 2842 | <para> |