aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/DMA-mapping.txt2
-rw-r--r--Documentation/RCU/whatisRCU.txt2
-rw-r--r--Documentation/block/biodoc.txt14
-rw-r--r--Documentation/cachetlb.txt21
-rw-r--r--Documentation/cpu-hotplug.txt4
-rw-r--r--Documentation/cputopology.txt4
-rw-r--r--Documentation/drivers/edac/edac.txt34
-rw-r--r--Documentation/filesystems/00-INDEX54
-rw-r--r--Documentation/ioctl-number.txt2
-rw-r--r--Documentation/m68k/README.buddha2
-rw-r--r--Documentation/networking/ifenslave.c2
-rw-r--r--Documentation/networking/vortex.txt81
-rw-r--r--Documentation/pnp.txt3
-rw-r--r--Documentation/robust-futex-ABI.txt182
-rw-r--r--Documentation/robust-futexes.txt218
-rw-r--r--Documentation/rpc-cache.txt121
-rw-r--r--Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl2
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.
203See linux/include/dma-mapping.h for reference.]
202 204
203When pci_set_dma_mask() is successful, and returns zero, the PCI layer 205When pci_set_dma_mask() is successful, and returns zero, the PCI layer
204saves away this mask you have provided. The PCI layer will use this 206saves 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
98You really dont need to manipulate any of the system cpu maps. They should 98You really dont need to manipulate any of the system cpu maps. They should
99be read-only for most use. When setting up per-cpu resources almost always use 99be read-only for most use. When setting up per-cpu resources almost always use
100cpu_possible_map/for_each_cpu() to iterate. 100cpu_possible_map/for_each_possible_cpu() to iterate.
101 101
102Never use anything other than cpumask_t to represent bitmap of CPUs. 102Never 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
106for_each_cpu - Iterate over cpu_possible_map 106for_each_possible_cpu - Iterate over cpu_possible_map
107for_each_online_cpu - Iterate over cpu_online_map 107for_each_online_cpu - Iterate over cpu_online_map
108for_each_present_cpu - Iterate over cpu_present_map 108for_each_present_cpu - Iterate over cpu_present_map
109for_each_cpu_mask(x,mask) - Iterate over some random collection of cpu mask. 109for_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
2Export cpu topology info by sysfs. Items (attributes) are similar 2Export cpu topology info via sysfs. Items (attributes) are similar
3to /proc/cpuinfo. 3to /proc/cpuinfo.
4 4
51) /sys/devices/system/cpu/cpuX/topology/physical_package_id: 51) /sys/devices/system/cpu/cpuX/topology/physical_package_id:
@@ -12,7 +12,7 @@ represent the thread siblings to cpu X in the same core;
12represent the thread siblings to cpu X in the same physical package; 12represent the thread siblings to cpu X in the same physical package;
13 13
14To implement it in an architecture-neutral way, a new source file, 14To implement it in an architecture-neutral way, a new source file,
15driver/base/topology.c, is to export the 5 attributes. 15drivers/base/topology.c, is to export the 4 attributes.
16 16
17If one architecture wants to support this feature, it just needs to 17If one architecture wants to support this feature, it just needs to
18implement 4 defines, typically in file include/asm-XXX/topology.h. 18implement 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
22Detecting CE events, then harvesting those events and reporting them, 22Detecting CE events, then harvesting those events and reporting them,
23CAN be a predictor of future UE events. With CE events, the system can 23CAN be a predictor of future UE events. With CE events, the system can
24continue to operate, but with less safety. Preventive maintainence and 24continue to operate, but with less safety. Preventive maintenance and
25proactive part replacement of memory DIMMs exhibiting CEs can reduce 25proactive part replacement of memory DIMMs exhibiting CEs can reduce
26the likelihood of the dreaded UE events and system 'panics'. 26the 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'.
29In addition, PCI Bus Parity and SERR Errors are scanned for on PCI devices 29In addition, PCI Bus Parity and SERR Errors are scanned for on PCI devices
30in order to determine if errors are occurring on data transfers. 30in order to determine if errors are occurring on data transfers.
31The presence of PCI Parity errors must be examined with a grain of salt. 31The presence of PCI Parity errors must be examined with a grain of salt.
32There are several addin adapters that do NOT follow the PCI specification 32There are several add-in adapters that do NOT follow the PCI specification
33with regards to Parity generation and reporting. The specification says 33with regards to Parity generation and reporting. The specification says
34the vendor should tie the parity status bits to 0 if they do not intend 34the vendor should tie the parity status bits to 0 if they do not intend
35to generate parity. Some vendors do not do this, and thus the parity bit 35to generate parity. Some vendors do not do this, and thus the parity bit
36can "float" giving false positives. 36can "float" giving false positives.
37 37
38The PCI Parity EDAC device has the ability to "skip" known flakey 38The PCI Parity EDAC device has the ability to "skip" known flaky
39cards during the parity scan. These are set by the parity "blacklist" 39cards during the parity scan. These are set by the parity "blacklist"
40interface in the sysfs for PCI Parity. (See the PCI section in the sysfs 40interface in the sysfs for PCI Parity. (See the PCI section in the sysfs
41section below.) There is also a parity "whitelist" which is used as 41section below.) There is also a parity "whitelist" which is used as
@@ -101,7 +101,7 @@ Memory Controller (mc) Model
101 101
102First a background on the memory controller's model abstracted in EDAC. 102First a background on the memory controller's model abstracted in EDAC.
103Each mc device controls a set of DIMM memory modules. These modules are 103Each mc device controls a set of DIMM memory modules. These modules are
104layed out in a Chip-Select Row (csrowX) and Channel table (chX). There can 104laid out in a Chip-Select Row (csrowX) and Channel table (chX). There can
105be multiple csrows and two channels. 105be multiple csrows and two channels.
106 106
107Memory controllers allow for several csrows, with 8 csrows being a typical value. 107Memory 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
133Labels for these slots are usually silk screened on the motherboard. Slots 133Labels for these slots are usually silk screened on the motherboard. Slots
134labeled 'A' are channel 0 in this example. Slots labled 'B' 134labeled 'A' are channel 0 in this example. Slots labeled 'B'
135are channel 1. Notice that there are two csrows possible on a 135are channel 1. Notice that there are two csrows possible on a
136physical DIMM. These csrows are allocated their csrow assignment 136physical DIMM. These csrows are allocated their csrow assignment
137based on the slot into which the memory DIMM is placed. Thus, when 1 DIMM 137based 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.
140Memory DIMMs come single or dual "ranked". A rank is a populated csrow. 140Memory DIMMs come single or dual "ranked". A rank is a populated csrow.
141Thus, 2 single ranked DIMMs, placed in slots DIMM_A0 and DIMM_B0 above 141Thus, 2 single ranked DIMMs, placed in slots DIMM_A0 and DIMM_B0 above
142will have 1 csrow, csrow0. csrow1 will be empty. On the other hand, 142will have 1 csrow, csrow0. csrow1 will be empty. On the other hand,
143when 2 dual ranked DIMMs are similiaryly placed, then both csrow0 and 143when 2 dual ranked DIMMs are similarly placed, then both csrow0 and
144csrow1 will be populated. The pattern repeats itself for csrow2 and 144csrow1 will be populated. The pattern repeats itself for csrow2 and
145csrow3. 145csrow3.
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
429Memory Type attribute file: 429Memory Type attribute file:
@@ -557,7 +557,7 @@ On Header Type 00 devices the primary status is looked at
557for any parity error regardless of whether Parity is enabled on the 557for any parity error regardless of whether Parity is enabled on the
558device. (The spec indicates parity is generated in some cases). 558device. (The spec indicates parity is generated in some cases).
559On Header Type 01 bridges, the secondary status register is also 559On Header Type 01 bridges, the secondary status register is also
560looked at to see if parity ocurred on the bus on the other side of 560looked at to see if parity occurred on the bus on the other side of
561the bridge. 561the 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
659PCI Vendor and Devices IDs can be obtained with the lspci command. Using 659PCI Vendor and Devices IDs can be obtained with the lspci command. Using
660the -n option lspci will display the vendor and device IDs. The system 660the -n option lspci will display the vendor and device IDs. The system
661adminstrator will have to determine which devices should be scanned or 661administrator will have to determine which devices should be scanned or
662skipped. 662skipped.
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
672and any previous blacklist will be utililzed. 672and 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 @@
100-INDEX 100-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).
3Exporting
4 - explanation of how to make filesystems exportable.
3Locking 5Locking
4 - info on locking rules as they pertain to Linux VFS. 6 - info on locking rules as they pertain to Linux VFS.
5adfs.txt 7adfs.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.
9afs.txt
10 - info and examples for the distributed AFS (Andrew File System) fs.
7affs.txt 11affs.txt
8 - info and mount options for the Amiga Fast File System. 12 - info and mount options for the Amiga Fast File System.
13automount-support.txt
14 - information about filesystem automount support.
15befs.txt
16 - information about the BeOS filesystem for Linux.
9bfs.txt 17bfs.txt
10 - info for the SCO UnixWare Boot Filesystem (BFS). 18 - info for the SCO UnixWare Boot Filesystem (BFS).
11cifs.txt 19cifs.txt
12 - description of the CIFS filesystem 20 - description of the CIFS filesystem.
13coda.txt 21coda.txt
14 - description of the CODA filesystem. 22 - description of the CODA filesystem.
15configfs/ 23configfs/
16 - directory containing configfs documentation and example code. 24 - directory containing configfs documentation and example code.
17cramfs.txt 25cramfs.txt
18 - info on the cram filesystem for small storage (ROMs etc) 26 - info on the cram filesystem for small storage (ROMs etc).
27dentry-locking.txt
28 - info on the RCU-based dcache locking model.
19devfs/ 29devfs/
20 - directory containing devfs documentation. 30 - directory containing devfs documentation.
31directory-locking
32 - info about the locking scheme used for directory operations.
21dlmfs.txt 33dlmfs.txt
22 - info on the userspace interface to the OCFS2 DLM. 34 - info on the userspace interface to the OCFS2 DLM.
23ext2.txt 35ext2.txt
24 - info, mount options and specifications for the Ext2 filesystem. 36 - info, mount options and specifications for the Ext2 filesystem.
37ext3.txt
38 - info, mount options and specifications for the Ext3 filesystem.
39files.txt
40 - info on file management in the Linux kernel.
41fuse.txt
42 - info on the Filesystem in User SpacE including mount options.
43hfs.txt
44 - info on the Macintosh HFS Filesystem for Linux.
25hpfs.txt 45hpfs.txt
26 - info and mount options for the OS/2 HPFS. 46 - info and mount options for the OS/2 HPFS.
27isofs.txt 47isofs.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.
33ntfs.txt 53ntfs.txt
34 - info and mount options for the NTFS filesystem (Windows NT). 54 - info and mount options for the NTFS filesystem (Windows NT).
35proc.txt
36 - info on Linux's /proc filesystem.
37ocfs2.txt 55ocfs2.txt
38 - info and mount options for the OCFS2 clustered filesystem. 56 - info and mount options for the OCFS2 clustered filesystem.
57porting
58 - various information on filesystem porting.
59proc.txt
60 - info on Linux's /proc filesystem.
61ramfs-rootfs-initramfs.txt
62 - info on the 'in memory' filesystems ramfs, rootfs and initramfs.
63reiser4.txt
64 - info on the Reiser4 filesystem based on dancing tree algorithms.
65relayfs.txt
66 - info on relayfs, for efficient streaming from kernel to user space.
39romfs.txt 67romfs.txt
40 - Description of the ROMFS filesystem. 68 - description of the ROMFS filesystem.
41smbfs.txt 69smbfs.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).
71spufs.txt
72 - info and mount options for the SPU filesystem used on Cell.
73sysfs-pci.txt
74 - info on accessing PCI device resources through sysfs.
75sysfs.txt
76 - info on sysfs, a ram-based filesystem for exporting kernel objects.
43sysv-fs.txt 77sysv-fs.txt
44 - info on the SystemV/V7/Xenix/Coherent filesystem. 78 - info on the SystemV/V7/Xenix/Coherent filesystem.
79tmpfs.txt
80 - info on tmpfs, a filesystem that holds all files in virtual memory.
45udf.txt 81udf.txt
46 - info and mount options for the UDF filesystem. 82 - info and mount options for the UDF filesystem.
47ufs.txt 83ufs.txt
48 - info on the ufs filesystem. 84 - info on the ufs filesystem.
85v9fs.txt
86 - v9fs is a Unix implementation of the Plan 9 9p remote fs protocol.
49vfat.txt 87vfat.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
51vfs.txt 89vfs.txt
52 - Overview of the Virtual File System 90 - overview of the Virtual File System
53xfs.txt 91xfs.txt
54 - info and mount options for the XFS filesystem. 92 - info and mount options for the XFS filesystem.
93xip.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
30as long as $48 is not touched. After $48 has been written, 30as long as $48 is not touched. After $48 has been written,
31the whole card disappears from $e8 and is mapped to the new 31the whole card disappears from $e8 and is mapped to the new
32address just written. Make shure $4a is written before $48, 32address just written. Make sure $4a is written before $48,
33otherwise your chance is only 1:16 to find the board :-). 33otherwise your chance is only 1:16 to find the board :-).
34 34
35The local memory-map is even active when mapped to $e8: 35The 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
25This driver supports the following hardware: 25This 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
58Module parameters 66Module 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
2963Com's documentation for many NICs, including the ones supported by
297this driver is available at
298
299 http://support.3com.com/partners/developer/developer_form.html
300
3013Com's DOS-based application for setting up the NICs EEPROMs: 3043Com'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
115pnp_register_driver 115pnp_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
119pnp_unregister_driver 122pnp_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 @@
1Started by Paul Jackson <pj@sgi.com>
2
3The robust futex ABI
4--------------------
5
6Robust_futexes provide a mechanism that is used in addition to normal
7futexes, for kernel assist of cleanup of held locks on task exit.
8
9The interesting data as to what futexes a thread is holding is kept on a
10linked list in user space, where it can be updated efficiently as locks
11are taken and dropped, without kernel intervention. The only additional
12kernel intervention required for robust_futexes above and beyond what is
13required 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
20The existing normal futexes already provide a "Fast Userspace Locking"
21mechanism, which handles uncontested locking without needing a system
22call, and handles contested locking by maintaining a list of waiting
23threads in the kernel. Options on the sys_futex(2) system call support
24waiting on a particular futex, and waking up the next waiter on a
25particular futex.
26
27For robust_futexes to work, the user code (typically in a library such
28as glibc linked with the application) has to manage and place the
29necessary list elements exactly as the kernel expects them. If it fails
30to do so, then improperly listed locks will not be cleaned up on exit,
31probably causing deadlock or other such failure of the other threads
32waiting on the same locks.
33
34A thread that anticipates possibly using robust_futexes should first
35issue the system call:
36
37 asmlinkage long
38 sys_set_robust_list(struct robust_list_head __user *head, size_t len);
39
40The pointer 'head' points to a structure in the threads address space
41consisting of three words. Each word is 32 bits on 32 bit arch's, or 64
42bits on 64 bit arch's, and local byte order. Each thread should have
43its own thread private 'head'.
44
45If a thread is running in 32 bit compatibility mode on a 64 native arch
46kernel, then it can actually have two such structures - one using 32 bit
47words for 32 bit compatibility mode, and one using 64 bit words for 64
48bit native mode. The kernel, if it is a 64 bit kernel supporting 32 bit
49compatibility mode, will attempt to process both lists on each task
50exit, if the corresponding sys_set_robust_list() call has been made to
51setup 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
71Each 'lock entry' on the single linked list starting at 'head' consists
72of 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
74entry', at an offset from the 'lock entry' specified by the 'offset'
75word, is one 'lock word'.
76
77The 'lock word' is always 32 bits, and is intended to be the same 32 bit
78lock variable used by the futex mechanism, in conjunction with
79robust_futexes. The kernel will only be able to wakeup the next thread
80waiting for a lock on a threads exit if that next thread used the futex
81mechanism to register the address of that 'lock word' with the kernel.
82
83For each futex lock currently held by a thread, if it wants this
84robust_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
86specified 'offset'. Should a thread die while holding any such locks,
87the kernel will walk this list, mark any such locks with a bit
88indicating their holder died, and wakeup the next thread waiting for
89that lock using the futex mechanism.
90
91When a thread has invoked the above system call to indicate it
92anticipates using robust_futexes, the kernel stores the passed in 'head'
93pointer for that task. The task may retrieve that value later on by
94using 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
100It is anticipated that threads will use robust_futexes embedded in
101larger, user level locking structures, one per lock. The kernel
102robust_futex mechanism doesn't care what else is in that structure, so
103long as the 'offset' to the 'lock word' is the same for all
104robust_futexes used by that thread. The thread should link those locks
105it currently holds using the 'lock entry' pointers. It may also have
106other links between the locks, such as the reverse side of a double
107linked list, but that doesn't matter to the kernel.
108
109By keeping its locks linked this way, on a list starting with a 'head'
110pointer known to the kernel, the kernel can provide to a thread the
111essential service available for robust_futexes, which is to help clean
112up locks held at the time of (a perhaps unexpectedly) exit.
113
114Actual locking and unlocking, during normal operations, is handled
115entirely by user level code in the contending threads, and by the
116existing futex mechanism to wait for, and wakeup, locks. The kernels
117only essential involvement in robust_futexes is to remember where the
118list 'head' is, and to walk the list on thread exit, handling locks
119still held by the departing thread, as described below.
120
121There may exist thousands of futex lock structures in a threads shared
122memory, on various data structures, at a given point in time. Only those
123lock structures for locks currently held by that thread should be on
124that thread's robust_futex linked lock list a given time.
125
126A given futex lock structure in a user shared memory region may be held
127at different times by any of the threads with access to that region. The
128thread currently holding such a lock, if any, is marked with the threads
129TID in the lower 29 bits of the 'lock word'.
130
131When adding or removing a lock from its list of held locks, in order for
132the kernel to correctly handle lock cleanup regardless of when the task
133exits (perhaps it gets an unexpected signal 9 in the middle of
134manipulating this list), the user code must observe the following
135protocol on 'lock entry' insertion and removal:
136
137On 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
145On 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
152On exit, the kernel will consider the address stored in
153'list_op_pending' and the address of each 'lock word' found by walking
154the list starting at 'head'. For each such address, if the bottom 29
155bits of the 'lock word' at offset 'offset' from that address equals the
156exiting 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
163In the above, bit 31 was set by futex waiters on that lock to indicate
164they were waiting, and bit 30 is set by the kernel to indicate that the
165lock owner died holding the lock.
166
167The kernel exit code will silently stop scanning the list further if at
168any 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
178When the kernel sees a list entry whose 'lock word' doesn't have the
179current threads TID in the lower 29 bits, it does nothing with that
180entry, and goes on to the next entry.
181
182Bit 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 @@
1Started by: Ingo Molnar <mingo@redhat.com>
2
3Background
4----------
5
6what are robust futexes? To answer that, we first need to understand
7what futexes are: normal futexes are special types of locks that in the
8noncontended case can be acquired/released from userspace without having
9to enter the kernel.
10
11A futex is in essence a user-space address, e.g. a 32-bit lock variable
12field. If userspace notices contention (the lock is already owned and
13someone else wants to grab it too) then the lock is marked with a value
14that says "there's a waiter pending", and the sys_futex(FUTEX_WAIT)
15syscall is used to wait for the other guy to release it. The kernel
16creates a 'futex queue' internally, so that it can later on match up the
17waiter with the waker - without them having to know about each other.
18When the owner thread releases the futex, it notices (via the variable
19value) that there were waiter(s) pending, and does the
20sys_futex(FUTEX_WAKE) syscall to wake them up. Once all waiters have
21taken and released the lock, the futex is again back to 'uncontended'
22state, and there's no in-kernel state associated with it. The kernel
23completely forgets that there ever was a futex at that address. This
24method makes futexes very lightweight and scalable.
25
26"Robustness" is about dealing with crashes while holding a lock: if a
27process exits prematurely while holding a pthread_mutex_t lock that is
28also shared with some other process (e.g. yum segfaults while holding a
29pthread_mutex_t, or yum is kill -9-ed), then waiters for that lock need
30to be notified that the last owner of the lock exited in some irregular
31way.
32
33To solve such types of problems, "robust mutex" userspace APIs were
34created: pthread_mutex_lock() returns an error value if the owner exits
35prematurely - and the new owner can decide whether the data protected by
36the lock can be recovered safely.
37
38There is a big conceptual problem with futex based mutexes though: it is
39the kernel that destroys the owner task (e.g. due to a SEGFAULT), but
40the 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)
42then the kernel has no information to clean up after the held lock!
43Userspace has no chance to clean up after the lock either - userspace is
44the one that crashes, so it has no opportunity to clean up. Catch-22.
45
46In practice, when e.g. yum is kill -9-ed (or segfaults), a system reboot
47is needed to release that futex based lock. This is one of the leading
48bugreports against yum.
49
50To solve this problem, the traditional approach was to extend the vma
51(virtual memory area descriptor) concept to have a notion of 'pending
52robust futexes attached to this area'. This approach requires 3 new
53syscall variants to sys_futex(): FUTEX_REGISTER, FUTEX_DEREGISTER and
54FUTEX_RECOVER. At do_exit() time, all vmas are searched to see whether
55they have a robust_head set. This approach has two fundamental problems
56left:
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
64The second disadvantage is a real killer: pthread_exit() takes around 1
65microsecond on Linux, but with thousands (or tens of thousands) of vmas
66every pthread_exit() takes a millisecond or more, also totally
67destroying the CPU's L1 and L2 caches!
68
69This is very much noticeable even for normal process sys_exit_group()
70calls: the kernel has to do the vma scanning unconditionally! (this is
71because the kernel has no knowledge about how many robust futexes there
72are to be cleaned up, because a robust futex might have been registered
73in another task, and the futex variable might have been simply mmap()-ed
74into this process's address space).
75
76This huge overhead forced the creation of CONFIG_FUTEX_ROBUST so that
77normal kernels can turn it off, but worse than that: the overhead makes
78robust futexes impractical for any type of generic Linux distribution.
79
80So something had to be done.
81
82New approach to robust futexes
83------------------------------
84
85At the heart of this new approach there is a per-thread private list of
86robust locks that userspace is holding (maintained by glibc) - which
87userspace list is registered with the kernel via a new syscall [this
88registration happens at most once per thread lifetime]. At do_exit()
89time, the kernel checks this user-space list: are there any robust futex
90locks to be cleaned up?
91
92In the common case, at do_exit() time, there is no list registered, so
93the cost of robust futexes is just a simple current->robust_list != NULL
94comparison. If the thread has registered a list, then normally the list
95is empty. If the thread/process crashed or terminated in some incorrect
96way then the list might be non-empty: in this case the kernel carefully
97walks the list [not trusting it], and marks all locks that are owned by
98this thread with the FUTEX_OWNER_DEAD bit, and wakes up one waiter (if
99any).
100
101The list is guaranteed to be private and per-thread at do_exit() time,
102so it can be accessed by the kernel in a lockless way.
103
104There is one race possible though: since adding to and removing from the
105list is done after the futex is acquired by glibc, there is a few
106instructions window for the thread (or process) to die there, leaving
107the futex hung. To protect against this possibility, userspace (glibc)
108also maintains a simple per-thread 'list_op_pending' field, to allow the
109kernel to clean up if the thread dies after acquiring the lock, but just
110before it could have added itself to the list. Glibc sets this
111list_op_pending field before it tries to acquire the futex, and clears
112it after the list-add (or list-remove) has finished.
113
114That's all that is needed - all the rest of robust-futex cleanup is done
115in userspace [just like with the previous patches].
116
117Ulrich Drepper has implemented the necessary glibc support for this new
118mechanism, which fully enables robust mutexes.
119
120Key differences of this userspace-list based approach, compared to the
121vma 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
144Performance
145-----------
146
147I have benchmarked the time needed for the kernel to process a list of 1
148million (!) 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
153I have also measured an approach where glibc does the lock notification
154[which it currently does for !pshared robust mutexes], and that took 256
155msecs - clearly slower, due to the 1 million FUTEX_WAKE syscalls
156userspace had to do.
157
158(1 million held locks are unheard of - we expect at most a handful of
159locks to be held at a time. Nevertheless it's nice to know that this
160approach scales nicely.)
161
162Implementation details
163----------------------
164
165The patch adds two new syscalls: one to register the userspace list, and
166one 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
176List registration is very fast: the pointer is simply stored in
177current->robust_list. [Note that in the future, if robust futexes become
178widespread, we could extend sys_clone() to register a robust-list head
179for new threads, without the need of another syscall.]
180
181So there is virtually zero overhead for tasks not using robust futexes,
182and even for robust futex users, there is only one extra syscall per
183thread lifetime, and the cleanup operation, if it happens, is fast and
184straightforward. The kernel doesnt have any internal distinction between
185robust and normal futexes.
186
187If a futex is found to be held at exit time, the kernel sets the
188following bit of the futex word:
189
190 #define FUTEX_OWNER_DIED 0x40000000
191
192and wakes up the next futex waiter (if any). User-space does the rest of
193the cleanup.
194
195Otherwise, robust futexes are acquired by glibc by putting the TID into
196the futex field atomically. Waiters set the FUTEX_WAITERS bit:
197
198 #define FUTEX_WAITERS 0x80000000
199
200and the remaining bits are for the TID.
201
202Testing, architecture support
203-----------------------------
204
205i've tested the new syscalls on x86 and x86_64, and have made sure the
206parsing of the userspace list is robust [ ;-) ] even if the list is
207deliberately corrupted.
208
209i386 and x86_64 syscalls are wired up at the moment, and Ulrich has
210tested the new glibc code (on x86_64 and i386), and it works for his
211robust-mutex testcases.
212
213All other architectures should build just fine too - but they wont have
214the new syscalls yet.
215
216Architectures need to implement the new futex_atomic_cmpxchg_inatomic()
217inline 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 @@
1This document gives a brief introduction to the caching 1 This document gives a brief introduction to the caching
2mechanisms in the sunrpc layer that is used, in particular, 2mechanisms in the sunrpc layer that is used, in particular,
3for NFS authentication. 3for 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
38The code for performing a cache lookup is also common, but in the form
39of a template. i.e. a #define.
40Each cache defines a lookup function by using the DefineCacheLookup
41macro, or the simpler DefineSimpleCacheLookup macro
42 34
43Creating a Cache 35Creating a Cache
44---------------- 36----------------
45 37
461/ A cache needs a datum to cache. This is in the form of a 381/ 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.
532/ A cache needs a "cache_detail" structure that 452/ 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
563/ 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 *)
634/ 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
913/ 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
68Using a cache 95Using a cache
69------------- 96-------------
70 97
71To find a value in a cache, call the lookup function passing it a the 98To find a value in a cache, call sunrpc_cache_lookup passing a pointer
72datum which contains key, and possibly content, and a flag saying 99to the cache_head in a sample item with the 'key' fields filled in.
73whether to update the cache with new data from the datum. Depending 100This will be passed to ->match to identify the target entry. If no
74on how the cache lookup function was defined, it may take an extra 101entry is found, a new entry will be create, added to the cache, and
75argument to identify the particular cache in question. 102marked as not containing valid data.
76 103
77Except in cases of kmalloc failure, the lookup function 104The item returned is typically passed to cache_check which will check
78will return a new datum which will store the key and 105if the data is valid, and may initiate an up-call to get fresh data.
79may contain valid content, or may not. 106cache_check will return -ENOENT in the entry is negative or if an up
80This datum is typically passed to cache_check which determines the 107call is needed but not possible, -EAGAIN if an upcall is pending,
81validity of the datum and may later initiate an upcall to fill 108or 0 if the data is valid;
82in the data.
83 109
84cache_check can be passed a "struct cache_req *". This structure is 110cache_check can be passed a "struct cache_req *". This structure is
85typically embedded in the actual request and can be used to create a 111typically 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
90revisited (->revisit). It is expected that this method will 116revisited (->revisit). It is expected that this method will
91reschedule the request for processing. 117reschedule the request for processing.
92 118
119The value returned by sunrpc_cache_lookup can also be passed to
120sunrpc_cache_update to set the content for the item. A second item is
121passed which should hold the content. If the item found by _lookup
122has valid data, then it is discarded and a new item is created. This
123saves any user of an item from worrying about content changing while
124it is being inspected. If the item found by _lookup does not contain
125valid data, then the content is copied across and CACHE_VALID is set.
93 126
94Populating a cache 127Populating a cache
95------------------ 128------------------
@@ -114,8 +147,8 @@ should be create or updated to have the given content, and the
114expiry time should be set on that item. 147expiry time should be set on that item.
115 148
116Reading from a channel is a bit more interesting. When a cache 149Reading from a channel is a bit more interesting. When a cache
117lookup fail, or when it suceeds but finds an entry that may soon 150lookup fails, or when it succeeds but finds an entry that may soon
118expiry, a request is lodged for that cache item to be updated by 151expire, a request is lodged for that cache item to be updated by
119user-space. These requests appear in the channel file. 152user-space. These requests appear in the channel file.
120 153
121Successive reads will return successive requests. 154Successive 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
133If it dies and needs to be restarted, any requests that have not be 166If it dies and needs to be restarted, any requests that have not been
134answered will still appear in the file and will be read by the new 167answered will still appear in the file and will be read by the new
135instance of the helper. 168instance of the helper.
136 169
@@ -142,10 +175,9 @@ Each cache should also define a "cache_request" method which
142takes a cache item and encodes a request into the buffer 175takes a cache item and encodes a request into the buffer
143provided. 176provided.
144 177
145
146Note: If a cache has no active readers on the channel, and has had not 178Note: If a cache has no active readers on the channel, and has had not
147active readers for more than 60 seconds, further requests will not be 179active readers for more than 60 seconds, further requests will not be
148added to the channel but instead all looks that do not find a valid 180added to the channel but instead all lookups that do not find a valid
149entry will fail. This is partly for backward compatibility: The 181entry will fail. This is partly for backward compatibility: The
150previous nfs exports table was deemed to be authoritative and a 182previous nfs exports table was deemed to be authoritative and a
151failed lookup meant a definite 'no'. 183failed lookup meant a definite 'no'.
@@ -154,18 +186,17 @@ request/response format
154----------------------- 186-----------------------
155 187
156While each cache is free to use it's own format for requests 188While each cache is free to use it's own format for requests
157and responses over channel, the following is recommended are 189and responses over channel, the following is recommended as
158appropriate and support routines are available to help: 190appropriate and support routines are available to help:
159Each request or response record should be printable ASCII 191Each request or response record should be printable ASCII
160with precisely one newline character which should be at the end. 192with precisely one newline character which should be at the end.
161Fields within the record should be separated by spaces, normally one. 193Fields within the record should be separated by spaces, normally one.
162If spaces, newlines, or nul characters are needed in a field they 194If spaces, newlines, or nul characters are needed in a field they
163much be quotes. two mechanisms are available: 195much be quoted. two mechanisms are available:
1641/ If a field begins '\x' then it must contain an even number of 1961/ 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.
1672/ otherwise a \ in the field must be followed by 3 octal digits 1992/ 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>