diff options
Diffstat (limited to 'Documentation')
30 files changed, 1431 insertions, 144 deletions
diff --git a/Documentation/ABI/obsolete/sysfs-class-rfkill b/Documentation/ABI/obsolete/sysfs-class-rfkill new file mode 100644 index 00000000000..4201d5b0551 --- /dev/null +++ b/Documentation/ABI/obsolete/sysfs-class-rfkill @@ -0,0 +1,29 @@ +rfkill - radio frequency (RF) connector kill switch support + +For details to this subsystem look at Documentation/rfkill.txt. + +What: /sys/class/rfkill/rfkill[0-9]+/state +Date: 09-Jul-2007 +KernelVersion v2.6.22 +Contact: linux-wireless@vger.kernel.org +Description: Current state of the transmitter. + This file is deprecated and sheduled to be removed in 2014, + because its not possible to express the 'soft and hard block' + state of the rfkill driver. +Values: A numeric value. + 0: RFKILL_STATE_SOFT_BLOCKED + transmitter is turned off by software + 1: RFKILL_STATE_UNBLOCKED + transmitter is (potentially) active + 2: RFKILL_STATE_HARD_BLOCKED + transmitter is forced off by something outside of + the driver's control. + +What: /sys/class/rfkill/rfkill[0-9]+/claim +Date: 09-Jul-2007 +KernelVersion v2.6.22 +Contact: linux-wireless@vger.kernel.org +Description: This file is deprecated because there no longer is a way to + claim just control over a single rfkill instance. + This file is scheduled to be removed in 2012. +Values: 0: Kernel handles events diff --git a/Documentation/ABI/stable/sysfs-class-rfkill b/Documentation/ABI/stable/sysfs-class-rfkill new file mode 100644 index 00000000000..097f522c33b --- /dev/null +++ b/Documentation/ABI/stable/sysfs-class-rfkill @@ -0,0 +1,67 @@ +rfkill - radio frequency (RF) connector kill switch support + +For details to this subsystem look at Documentation/rfkill.txt. + +For the deprecated /sys/class/rfkill/*/state and +/sys/class/rfkill/*/claim knobs of this interface look in +Documentation/ABI/obsolete/sysfs-class-rfkill. + +What: /sys/class/rfkill +Date: 09-Jul-2007 +KernelVersion: v2.6.22 +Contact: linux-wireless@vger.kernel.org, +Description: The rfkill class subsystem folder. + Each registered rfkill driver is represented by an rfkillX + subfolder (X being an integer > 0). + + +What: /sys/class/rfkill/rfkill[0-9]+/name +Date: 09-Jul-2007 +KernelVersion v2.6.22 +Contact: linux-wireless@vger.kernel.org +Description: Name assigned by driver to this key (interface or driver name). +Values: arbitrary string. + + +What: /sys/class/rfkill/rfkill[0-9]+/type +Date: 09-Jul-2007 +KernelVersion v2.6.22 +Contact: linux-wireless@vger.kernel.org +Description: Driver type string ("wlan", "bluetooth", etc). +Values: See include/linux/rfkill.h. + + +What: /sys/class/rfkill/rfkill[0-9]+/persistent +Date: 09-Jul-2007 +KernelVersion v2.6.22 +Contact: linux-wireless@vger.kernel.org +Description: Whether the soft blocked state is initialised from non-volatile + storage at startup. +Values: A numeric value. + 0: false + 1: true + + +What: /sys/class/rfkill/rfkill[0-9]+/hard +Date: 12-March-2010 +KernelVersion v2.6.34 +Contact: linux-wireless@vger.kernel.org +Description: Current hardblock state. This file is read only. +Values: A numeric value. + 0: inactive + The transmitter is (potentially) active. + 1: active + The transmitter is forced off by something outside of + the driver's control. + + +What: /sys/class/rfkill/rfkill[0-9]+/soft +Date: 12-March-2010 +KernelVersion v2.6.34 +Contact: linux-wireless@vger.kernel.org +Description: Current softblock state. This file is read and write. +Values: A numeric value. + 0: inactive + The transmitter is (potentially) active. + 1: active + The transmitter is turned off by software. diff --git a/Documentation/ABI/testing/sysfs-bus-usb b/Documentation/ABI/testing/sysfs-bus-usb index a986e9bbba3..bcebb9eaedc 100644 --- a/Documentation/ABI/testing/sysfs-bus-usb +++ b/Documentation/ABI/testing/sysfs-bus-usb @@ -160,7 +160,7 @@ Description: match the driver to the device. For example: # echo "046d c315" > /sys/bus/usb/drivers/foo/remove_id -What: /sys/bus/usb/device/.../avoid_reset +What: /sys/bus/usb/device/.../avoid_reset_quirk Date: December 2009 Contact: Oliver Neukum <oliver@neukum.org> Description: diff --git a/Documentation/PCI/PCI-DMA-mapping.txt b/Documentation/DMA-API-HOWTO.txt index 52618ab069a..52618ab069a 100644 --- a/Documentation/PCI/PCI-DMA-mapping.txt +++ b/Documentation/DMA-API-HOWTO.txt diff --git a/Documentation/DocBook/tracepoint.tmpl b/Documentation/DocBook/tracepoint.tmpl index 8bca1d5cec0..e8473eae2a2 100644 --- a/Documentation/DocBook/tracepoint.tmpl +++ b/Documentation/DocBook/tracepoint.tmpl @@ -16,6 +16,15 @@ </address> </affiliation> </author> + <author> + <firstname>William</firstname> + <surname>Cohen</surname> + <affiliation> + <address> + <email>wcohen@redhat.com</email> + </address> + </affiliation> + </author> </authorgroup> <legalnotice> @@ -91,4 +100,8 @@ !Iinclude/trace/events/signal.h </chapter> + <chapter id="block"> + <title>Block IO</title> +!Iinclude/trace/events/block.h + </chapter> </book> diff --git a/Documentation/block/biodoc.txt b/Documentation/block/biodoc.txt index 6fab97ea7e6..508b5b2b028 100644 --- a/Documentation/block/biodoc.txt +++ b/Documentation/block/biodoc.txt @@ -1162,8 +1162,8 @@ where a driver received a request ala this before: As mentioned, there is no virtual mapping of a bio. For DMA, this is not a problem as the driver probably never will need a virtual mapping. -Instead it needs a bus mapping (pci_map_page for a single segment or -use blk_rq_map_sg for scatter gather) to be able to ship it to the driver. For +Instead it needs a bus mapping (dma_map_page for a single segment or +use dma_map_sg for scatter gather) to be able to ship it to the driver. For PIO drivers (or drivers that need to revert to PIO transfer once in a while (IDE for example)), where the CPU is doing the actual data transfer a virtual mapping is needed. If the driver supports highmem I/O, diff --git a/Documentation/cgroups/memory.txt b/Documentation/cgroups/memory.txt index f8bc802d70b..3a6aecd078b 100644 --- a/Documentation/cgroups/memory.txt +++ b/Documentation/cgroups/memory.txt @@ -340,7 +340,7 @@ Note: 5.3 swappiness Similar to /proc/sys/vm/swappiness, but affecting a hierarchy of groups only. - Following cgroups' swapiness can't be changed. + Following cgroups' swappiness can't be changed. - root cgroup (uses /proc/sys/vm/swappiness). - a cgroup which uses hierarchy and it has child cgroup. - a cgroup which uses hierarchy and not the root of hierarchy. diff --git a/Documentation/circular-buffers.txt b/Documentation/circular-buffers.txt new file mode 100644 index 00000000000..8117e5bf606 --- /dev/null +++ b/Documentation/circular-buffers.txt @@ -0,0 +1,234 @@ + ================ + CIRCULAR BUFFERS + ================ + +By: David Howells <dhowells@redhat.com> + Paul E. McKenney <paulmck@linux.vnet.ibm.com> + + +Linux provides a number of features that can be used to implement circular +buffering. There are two sets of such features: + + (1) Convenience functions for determining information about power-of-2 sized + buffers. + + (2) Memory barriers for when the producer and the consumer of objects in the + buffer don't want to share a lock. + +To use these facilities, as discussed below, there needs to be just one +producer and just one consumer. It is possible to handle multiple producers by +serialising them, and to handle multiple consumers by serialising them. + + +Contents: + + (*) What is a circular buffer? + + (*) Measuring power-of-2 buffers. + + (*) Using memory barriers with circular buffers. + - The producer. + - The consumer. + + +========================== +WHAT IS A CIRCULAR BUFFER? +========================== + +First of all, what is a circular buffer? A circular buffer is a buffer of +fixed, finite size into which there are two indices: + + (1) A 'head' index - the point at which the producer inserts items into the + buffer. + + (2) A 'tail' index - the point at which the consumer finds the next item in + the buffer. + +Typically when the tail pointer is equal to the head pointer, the buffer is +empty; and the buffer is full when the head pointer is one less than the tail +pointer. + +The head index is incremented when items are added, and the tail index when +items are removed. The tail index should never jump the head index, and both +indices should be wrapped to 0 when they reach the end of the buffer, thus +allowing an infinite amount of data to flow through the buffer. + +Typically, items will all be of the same unit size, but this isn't strictly +required to use the techniques below. The indices can be increased by more +than 1 if multiple items or variable-sized items are to be included in the +buffer, provided that neither index overtakes the other. The implementer must +be careful, however, as a region more than one unit in size may wrap the end of +the buffer and be broken into two segments. + + +============================ +MEASURING POWER-OF-2 BUFFERS +============================ + +Calculation of the occupancy or the remaining capacity of an arbitrarily sized +circular buffer would normally be a slow operation, requiring the use of a +modulus (divide) instruction. However, if the buffer is of a power-of-2 size, +then a much quicker bitwise-AND instruction can be used instead. + +Linux provides a set of macros for handling power-of-2 circular buffers. These +can be made use of by: + + #include <linux/circ_buf.h> + +The macros are: + + (*) Measure the remaining capacity of a buffer: + + CIRC_SPACE(head_index, tail_index, buffer_size); + + This returns the amount of space left in the buffer[1] into which items + can be inserted. + + + (*) Measure the maximum consecutive immediate space in a buffer: + + CIRC_SPACE_TO_END(head_index, tail_index, buffer_size); + + This returns the amount of consecutive space left in the buffer[1] into + which items can be immediately inserted without having to wrap back to the + beginning of the buffer. + + + (*) Measure the occupancy of a buffer: + + CIRC_CNT(head_index, tail_index, buffer_size); + + This returns the number of items currently occupying a buffer[2]. + + + (*) Measure the non-wrapping occupancy of a buffer: + + CIRC_CNT_TO_END(head_index, tail_index, buffer_size); + + This returns the number of consecutive items[2] that can be extracted from + the buffer without having to wrap back to the beginning of the buffer. + + +Each of these macros will nominally return a value between 0 and buffer_size-1, +however: + + [1] CIRC_SPACE*() are intended to be used in the producer. To the producer + they will return a lower bound as the producer controls the head index, + but the consumer may still be depleting the buffer on another CPU and + moving the tail index. + + To the consumer it will show an upper bound as the producer may be busy + depleting the space. + + [2] CIRC_CNT*() are intended to be used in the consumer. To the consumer they + will return a lower bound as the consumer controls the tail index, but the + producer may still be filling the buffer on another CPU and moving the + head index. + + To the producer it will show an upper bound as the consumer may be busy + emptying the buffer. + + [3] To a third party, the order in which the writes to the indices by the + producer and consumer become visible cannot be guaranteed as they are + independent and may be made on different CPUs - so the result in such a + situation will merely be a guess, and may even be negative. + + +=========================================== +USING MEMORY BARRIERS WITH CIRCULAR BUFFERS +=========================================== + +By using memory barriers in conjunction with circular buffers, you can avoid +the need to: + + (1) use a single lock to govern access to both ends of the buffer, thus + allowing the buffer to be filled and emptied at the same time; and + + (2) use atomic counter operations. + +There are two sides to this: the producer that fills the buffer, and the +consumer that empties it. Only one thing should be filling a buffer at any one +time, and only one thing should be emptying a buffer at any one time, but the +two sides can operate simultaneously. + + +THE PRODUCER +------------ + +The producer will look something like this: + + spin_lock(&producer_lock); + + unsigned long head = buffer->head; + unsigned long tail = ACCESS_ONCE(buffer->tail); + + if (CIRC_SPACE(head, tail, buffer->size) >= 1) { + /* insert one item into the buffer */ + struct item *item = buffer[head]; + + produce_item(item); + + smp_wmb(); /* commit the item before incrementing the head */ + + buffer->head = (head + 1) & (buffer->size - 1); + + /* wake_up() will make sure that the head is committed before + * waking anyone up */ + wake_up(consumer); + } + + spin_unlock(&producer_lock); + +This will instruct the CPU that the contents of the new item must be written +before the head index makes it available to the consumer and then instructs the +CPU that the revised head index must be written before the consumer is woken. + +Note that wake_up() doesn't have to be the exact mechanism used, but whatever +is used must guarantee a (write) memory barrier between the update of the head +index and the change of state of the consumer, if a change of state occurs. + + +THE CONSUMER +------------ + +The consumer will look something like this: + + spin_lock(&consumer_lock); + + unsigned long head = ACCESS_ONCE(buffer->head); + unsigned long tail = buffer->tail; + + if (CIRC_CNT(head, tail, buffer->size) >= 1) { + /* read index before reading contents at that index */ + smp_read_barrier_depends(); + + /* extract one item from the buffer */ + struct item *item = buffer[tail]; + + consume_item(item); + + smp_mb(); /* finish reading descriptor before incrementing tail */ + + buffer->tail = (tail + 1) & (buffer->size - 1); + } + + spin_unlock(&consumer_lock); + +This will instruct the CPU to make sure the index is up to date before reading +the new item, and then it shall make sure the CPU has finished reading the item +before it writes the new tail pointer, which will erase the item. + + +Note the use of ACCESS_ONCE() in both algorithms to read the opposition index. +This prevents the compiler from discarding and reloading its cached value - +which some compilers will do across smp_read_barrier_depends(). This isn't +strictly needed if you can be sure that the opposition index will _only_ be +used the once. + + +=============== +FURTHER READING +=============== + +See also Documentation/memory-barriers.txt for a description of Linux's memory +barrier facilities. diff --git a/Documentation/connector/cn_test.c b/Documentation/connector/cn_test.c index b07add3467f..7764594778d 100644 --- a/Documentation/connector/cn_test.c +++ b/Documentation/connector/cn_test.c @@ -25,6 +25,7 @@ #include <linux/module.h> #include <linux/moduleparam.h> #include <linux/skbuff.h> +#include <linux/slab.h> #include <linux/timer.h> #include <linux/connector.h> diff --git a/Documentation/fb/imacfb.txt b/Documentation/fb/efifb.txt index 316ec9bb7de..a59916c29b3 100644 --- a/Documentation/fb/imacfb.txt +++ b/Documentation/fb/efifb.txt @@ -1,9 +1,9 @@ -What is imacfb? +What is efifb? =============== This is a generic EFI platform driver for Intel based Apple computers. -Imacfb is only for EFI booted Intel Macs. +efifb is only for EFI booted Intel Macs. Supported Hardware ================== @@ -16,16 +16,16 @@ MacMini How to use it? ============== -Imacfb does not have any kind of autodetection of your machine. +efifb does not have any kind of autodetection of your machine. You have to add the following kernel parameters in your elilo.conf: Macbook : - video=imacfb:macbook + video=efifb:macbook MacMini : - video=imacfb:mini + video=efifb:mini Macbook Pro 15", iMac 17" : - video=imacfb:i17 + video=efifb:i17 Macbook Pro 17", iMac 20" : - video=imacfb:i20 + video=efifb:i20 -- Edgar Hucek <gimli@dark-green.com> diff --git a/Documentation/feature-removal-schedule.txt b/Documentation/feature-removal-schedule.txt index ea227e3f528..a1c6e927798 100644 --- a/Documentation/feature-removal-schedule.txt +++ b/Documentation/feature-removal-schedule.txt @@ -533,6 +533,24 @@ Who: Eric Miao <eric.y.miao@gmail.com> ---------------------------- +What: sysfs-class-rfkill state file +When: Feb 2014 +Files: net/rfkill/core.c +Why: Documented as obsolete since Feb 2010. This file is limited to 3 + states while the rfkill drivers can have 4 states. +Who: anybody or Florian Mickler <florian@mickler.org> + +---------------------------- + +What: sysfs-class-rfkill claim file +When: Feb 2012 +Files: net/rfkill/core.c +Why: It is not possible to claim an rfkill driver since 2007. This is + Documented as obsolete since Feb 2010. +Who: anybody or Florian Mickler <florian@mickler.org> + +---------------------------- + What: capifs When: February 2011 Files: drivers/isdn/capi/capifs.* @@ -580,6 +598,27 @@ Why: Useful in 2003, implementation is a hack. Seen as doing more harm than good. Who: Len Brown <len.brown@intel.com> +---------------------------- + +What: iwlwifi 50XX module parameters +When: 2.6.40 +Why: The "..50" modules parameters were used to configure 5000 series and + up devices; different set of module parameters also available for 4965 + with same functionalities. Consolidate both set into single place + in drivers/net/wireless/iwlwifi/iwl-agn.c + +Who: Wey-Yi Guy <wey-yi.w.guy@intel.com> + +---------------------------- + +What: iwl4965 alias support +When: 2.6.40 +Why: Internal alias support has been present in module-init-tools for some + time, the MODULE_ALIAS("iwl4965") boilerplate aliases can be removed + with no impact. + +Who: Wey-Yi Guy <wey-yi.w.guy@intel.com> + --------------------------- What: xt_NOTRACK diff --git a/Documentation/filesystems/00-INDEX b/Documentation/filesystems/00-INDEX index 3bae418c6ad..4303614b5ad 100644 --- a/Documentation/filesystems/00-INDEX +++ b/Documentation/filesystems/00-INDEX @@ -16,6 +16,8 @@ befs.txt - information about the BeOS filesystem for Linux. bfs.txt - info for the SCO UnixWare Boot Filesystem (BFS). +ceph.txt + - info for the Ceph Distributed File System cifs.txt - description of the CIFS filesystem. coda.txt diff --git a/Documentation/filesystems/9p.txt b/Documentation/filesystems/9p.txt index 57e0b80a527..c0236e753bc 100644 --- a/Documentation/filesystems/9p.txt +++ b/Documentation/filesystems/9p.txt @@ -37,6 +37,15 @@ For Plan 9 From User Space applications (http://swtch.com/plan9) mount -t 9p `namespace`/acme /mnt/9 -o trans=unix,uname=$USER +For server running on QEMU host with virtio transport: + + mount -t 9p -o trans=virtio <mount_tag> /mnt/9 + +where mount_tag is the tag associated by the server to each of the exported +mount points. Each 9P export is seen by the client as a virtio device with an +associated "mount_tag" property. Available mount tags can be +seen by reading /sys/bus/virtio/drivers/9pnet_virtio/virtio<n>/mount_tag files. + OPTIONS ======= @@ -47,7 +56,7 @@ OPTIONS fd - used passed file descriptors for connection (see rfdno and wfdno) virtio - connect to the next virtio channel available - (from lguest or KVM with trans_virtio module) + (from QEMU with trans_virtio module) rdma - connect to a specified RDMA channel uname=name user name to attempt mount as on the remote server. The @@ -85,7 +94,12 @@ OPTIONS port=n port to connect to on the remote server - noextend force legacy mode (no 9p2000.u semantics) + noextend force legacy mode (no 9p2000.u or 9p2000.L semantics) + + version=name Select 9P protocol version. Valid options are: + 9p2000 - Legacy mode (same as noextend) + 9p2000.u - Use 9P2000.u protocol + 9p2000.L - Use 9P2000.L protocol dfltuid attempt to mount as a particular uid diff --git a/Documentation/filesystems/ceph.txt b/Documentation/filesystems/ceph.txt new file mode 100644 index 00000000000..0660c9f5dee --- /dev/null +++ b/Documentation/filesystems/ceph.txt @@ -0,0 +1,140 @@ +Ceph Distributed File System +============================ + +Ceph is a distributed network file system designed to provide good +performance, reliability, and scalability. + +Basic features include: + + * POSIX semantics + * Seamless scaling from 1 to many thousands of nodes + * High availability and reliability. No single point of failure. + * N-way replication of data across storage nodes + * Fast recovery from node failures + * Automatic rebalancing of data on node addition/removal + * Easy deployment: most FS components are userspace daemons + +Also, + * Flexible snapshots (on any directory) + * Recursive accounting (nested files, directories, bytes) + +In contrast to cluster filesystems like GFS, OCFS2, and GPFS that rely +on symmetric access by all clients to shared block devices, Ceph +separates data and metadata management into independent server +clusters, similar to Lustre. Unlike Lustre, however, metadata and +storage nodes run entirely as user space daemons. Storage nodes +utilize btrfs to store data objects, leveraging its advanced features +(checksumming, metadata replication, etc.). File data is striped +across storage nodes in large chunks to distribute workload and +facilitate high throughputs. When storage nodes fail, data is +re-replicated in a distributed fashion by the storage nodes themselves +(with some minimal coordination from a cluster monitor), making the +system extremely efficient and scalable. + +Metadata servers effectively form a large, consistent, distributed +in-memory cache above the file namespace that is extremely scalable, +dynamically redistributes metadata in response to workload changes, +and can tolerate arbitrary (well, non-Byzantine) node failures. The +metadata server takes a somewhat unconventional approach to metadata +storage to significantly improve performance for common workloads. In +particular, inodes with only a single link are embedded in +directories, allowing entire directories of dentries and inodes to be +loaded into its cache with a single I/O operation. The contents of +extremely large directories can be fragmented and managed by +independent metadata servers, allowing scalable concurrent access. + +The system offers automatic data rebalancing/migration when scaling +from a small cluster of just a few nodes to many hundreds, without +requiring an administrator carve the data set into static volumes or +go through the tedious process of migrating data between servers. +When the file system approaches full, new nodes can be easily added +and things will "just work." + +Ceph includes flexible snapshot mechanism that allows a user to create +a snapshot on any subdirectory (and its nested contents) in the +system. Snapshot creation and deletion are as simple as 'mkdir +.snap/foo' and 'rmdir .snap/foo'. + +Ceph also provides some recursive accounting on directories for nested +files and bytes. That is, a 'getfattr -d foo' on any directory in the +system will reveal the total number of nested regular files and +subdirectories, and a summation of all nested file sizes. This makes +the identification of large disk space consumers relatively quick, as +no 'du' or similar recursive scan of the file system is required. + + +Mount Syntax +============ + +The basic mount syntax is: + + # mount -t ceph monip[:port][,monip2[:port]...]:/[subdir] mnt + +You only need to specify a single monitor, as the client will get the +full list when it connects. (However, if the monitor you specify +happens to be down, the mount won't succeed.) The port can be left +off if the monitor is using the default. So if the monitor is at +1.2.3.4, + + # mount -t ceph 1.2.3.4:/ /mnt/ceph + +is sufficient. If /sbin/mount.ceph is installed, a hostname can be +used instead of an IP address. + + + +Mount Options +============= + + ip=A.B.C.D[:N] + Specify the IP and/or port the client should bind to locally. + There is normally not much reason to do this. If the IP is not + specified, the client's IP address is determined by looking at the + address it's connection to the monitor originates from. + + wsize=X + Specify the maximum write size in bytes. By default there is no + maximum. Ceph will normally size writes based on the file stripe + size. + + rsize=X + Specify the maximum readahead. + + mount_timeout=X + Specify the timeout value for mount (in seconds), in the case + of a non-responsive Ceph file system. The default is 30 + seconds. + + rbytes + When stat() is called on a directory, set st_size to 'rbytes', + the summation of file sizes over all files nested beneath that + directory. This is the default. + + norbytes + When stat() is called on a directory, set st_size to the + number of entries in that directory. + + nocrc + Disable CRC32C calculation for data writes. If set, the storage node + must rely on TCP's error correction to detect data corruption + in the data payload. + + noasyncreaddir + Disable client's use its local cache to satisfy readdir + requests. (This does not change correctness; the client uses + cached metadata only when a lease or capability ensures it is + valid.) + + +More Information +================ + +For more information on Ceph, see the home page at + http://ceph.newdream.net/ + +The Linux kernel client source tree is available at + git://ceph.newdream.net/git/ceph-client.git + git://git.kernel.org/pub/scm/linux/kernel/git/sage/ceph-client.git + +and the source for the full system is at + git://ceph.newdream.net/git/ceph.git diff --git a/Documentation/filesystems/tmpfs.txt b/Documentation/filesystems/tmpfs.txt index 3015da0c6b2..fe09a2cb185 100644 --- a/Documentation/filesystems/tmpfs.txt +++ b/Documentation/filesystems/tmpfs.txt @@ -82,11 +82,13 @@ tmpfs has a mount option to set the NUMA memory allocation policy for all files in that instance (if CONFIG_NUMA is enabled) - which can be adjusted on the fly via 'mount -o remount ...' -mpol=default prefers to allocate memory from the local node +mpol=default use the process allocation policy + (see set_mempolicy(2)) mpol=prefer:Node prefers to allocate memory from the given Node mpol=bind:NodeList allocates memory only from nodes in NodeList mpol=interleave prefers to allocate from each node in turn mpol=interleave:NodeList allocates from each node of NodeList in turn +mpol=local prefers to allocate memory from the local node NodeList format is a comma-separated list of decimal numbers and ranges, a range being two hyphen-separated decimal numbers, the smallest and @@ -134,3 +136,5 @@ Author: Christoph Rohland <cr@sap.com>, 1.12.01 Updated: Hugh Dickins, 4 June 2007 +Updated: + KOSAKI Motohiro, 16 Mar 2010 diff --git a/Documentation/ioctl/ioctl-number.txt b/Documentation/ioctl/ioctl-number.txt index 35c9b51d20e..dd5806f4fcc 100644 --- a/Documentation/ioctl/ioctl-number.txt +++ b/Documentation/ioctl/ioctl-number.txt @@ -291,6 +291,7 @@ Code Seq#(hex) Include File Comments 0x92 00-0F drivers/usb/mon/mon_bin.c 0x93 60-7F linux/auto_fs.h 0x94 all fs/btrfs/ioctl.h +0x97 00-7F fs/ceph/ioctl.h Ceph file system 0x99 00-0F 537-Addinboard driver <mailto:buk@buks.ipn.de> 0xA0 all linux/sdp/sdp.h Industrial Device Project diff --git a/Documentation/kobject.txt b/Documentation/kobject.txt index bdb13817e1e..3ab2472509c 100644 --- a/Documentation/kobject.txt +++ b/Documentation/kobject.txt @@ -59,37 +59,56 @@ nice to have in other objects. The C language does not allow for the direct expression of inheritance, so other techniques - such as structure embedding - must be used. -So, for example, the UIO code has a structure that defines the memory -region associated with a uio device: +(As an aside, for those familiar with the kernel linked list implementation, +this is analogous as to how "list_head" structs are rarely useful on +their own, but are invariably found embedded in the larger objects of +interest.) -struct uio_mem { +So, for example, the UIO code in drivers/uio/uio.c has a structure that +defines the memory region associated with a uio device: + + struct uio_map { struct kobject kobj; - unsigned long addr; - unsigned long size; - int memtype; - void __iomem *internal_addr; -}; + struct uio_mem *mem; + }; -If you have a struct uio_mem structure, finding its embedded kobject is +If you have a struct uio_map structure, finding its embedded kobject is just a matter of using the kobj member. Code that works with kobjects will often have the opposite problem, however: given a struct kobject pointer, what is the pointer to the containing structure? You must avoid tricks (such as assuming that the kobject is at the beginning of the structure) and, instead, use the container_of() macro, found in <linux/kernel.h>: - container_of(pointer, type, member) + container_of(pointer, type, member) + +where: + + * "pointer" is the pointer to the embedded kobject, + * "type" is the type of the containing structure, and + * "member" is the name of the structure field to which "pointer" points. + +The return value from container_of() is a pointer to the corresponding +container type. So, for example, a pointer "kp" to a struct kobject +embedded *within* a struct uio_map could be converted to a pointer to the +*containing* uio_map structure with: + + struct uio_map *u_map = container_of(kp, struct uio_map, kobj); + +For convenience, programmers often define a simple macro for "back-casting" +kobject pointers to the containing type. Exactly this happens in the +earlier drivers/uio/uio.c, as you can see here: + + struct uio_map { + struct kobject kobj; + struct uio_mem *mem; + }; -where pointer is the pointer to the embedded kobject, type is the type of -the containing structure, and member is the name of the structure field to -which pointer points. The return value from container_of() is a pointer to -the given type. So, for example, a pointer "kp" to a struct kobject -embedded within a struct uio_mem could be converted to a pointer to the -containing uio_mem structure with: + #define to_map(map) container_of(map, struct uio_map, kobj) - struct uio_mem *u_mem = container_of(kp, struct uio_mem, kobj); +where the macro argument "map" is a pointer to the struct kobject in +question. That macro is subsequently invoked with: -Programmers often define a simple macro for "back-casting" kobject pointers -to the containing type. + struct uio_map *map = to_map(kobj); Initialization of kobjects @@ -387,4 +406,5 @@ called, and the objects in the former circle release each other. Example code to copy from For a more complete example of using ksets and kobjects properly, see the -sample/kobject/kset-example.c code. +example programs samples/kobject/{kobject-example.c,kset-example.c}, +which will be built as loadable modules if you select CONFIG_SAMPLE_KOBJECT. diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt index 7f5809eddee..631ad2f1b22 100644 --- a/Documentation/memory-barriers.txt +++ b/Documentation/memory-barriers.txt @@ -3,6 +3,7 @@ ============================ By: David Howells <dhowells@redhat.com> + Paul E. McKenney <paulmck@linux.vnet.ibm.com> Contents: @@ -60,6 +61,10 @@ Contents: - And then there's the Alpha. + (*) Example uses. + + - Circular buffers. + (*) References. @@ -2226,6 +2231,21 @@ The Alpha defines the Linux kernel's memory barrier model. See the subsection on "Cache Coherency" above. +============ +EXAMPLE USES +============ + +CIRCULAR BUFFERS +---------------- + +Memory barriers can be used to implement circular buffering without the need +of a lock to serialise the producer with the consumer. See: + + Documentation/circular-buffers.txt + +for details. + + ========== REFERENCES ========== diff --git a/Documentation/networking/caif/Linux-CAIF.txt b/Documentation/networking/caif/Linux-CAIF.txt new file mode 100644 index 00000000000..7fe7a9a33a4 --- /dev/null +++ b/Documentation/networking/caif/Linux-CAIF.txt @@ -0,0 +1,212 @@ +Linux CAIF +=========== +copyright (C) ST-Ericsson AB 2010 +Author: Sjur Brendeland/ sjur.brandeland@stericsson.com +License terms: GNU General Public License (GPL) version 2 + + +Introduction +------------ +CAIF is a MUX protocol used by ST-Ericsson cellular modems for +communication between Modem and host. The host processes can open virtual AT +channels, initiate GPRS Data connections, Video channels and Utility Channels. +The Utility Channels are general purpose pipes between modem and host. + +ST-Ericsson modems support a number of transports between modem +and host. Currently, UART and Loopback are available for Linux. + + +Architecture: +------------ +The implementation of CAIF is divided into: +* CAIF Socket Layer, Kernel API, and Net Device. +* CAIF Core Protocol Implementation +* CAIF Link Layer, implemented as NET devices. + + + RTNL + ! + ! +------+ +------+ +------+ + ! +------+! +------+! +------+! + ! ! Sock !! !Kernel!! ! Net !! + ! ! API !+ ! API !+ ! Dev !+ <- CAIF Client APIs + ! +------+ +------! +------+ + ! ! ! ! + ! +----------!----------+ + ! +------+ <- CAIF Protocol Implementation + +-------> ! CAIF ! + ! Core ! + +------+ + +--------!--------+ + ! ! + +------+ +-----+ + ! ! ! TTY ! <- Link Layer (Net Devices) + +------+ +-----+ + + +Using the Kernel API +---------------------- +The Kernel API is used for accessing CAIF channels from the +kernel. +The user of the API has to implement two callbacks for receive +and control. +The receive callback gives a CAIF packet as a SKB. The control +callback will +notify of channel initialization complete, and flow-on/flow- +off. + + + struct caif_device caif_dev = { + .caif_config = { + .name = "MYDEV" + .type = CAIF_CHTY_AT + } + .receive_cb = my_receive, + .control_cb = my_control, + }; + caif_add_device(&caif_dev); + caif_transmit(&caif_dev, skb); + +See the caif_kernel.h for details about the CAIF kernel API. + + +I M P L E M E N T A T I O N +=========================== +=========================== + +CAIF Core Protocol Layer +========================================= + +CAIF Core layer implements the CAIF protocol as defined by ST-Ericsson. +It implements the CAIF protocol stack in a layered approach, where +each layer described in the specification is implemented as a separate layer. +The architecture is inspired by the design patterns "Protocol Layer" and +"Protocol Packet". + +== CAIF structure == +The Core CAIF implementation contains: + - Simple implementation of CAIF. + - Layered architecture (a la Streams), each layer in the CAIF + specification is implemented in a separate c-file. + - Clients must implement PHY layer to access physical HW + with receive and transmit functions. + - Clients must call configuration function to add PHY layer. + - Clients must implement CAIF layer to consume/produce + CAIF payload with receive and transmit functions. + - Clients must call configuration function to add and connect the + Client layer. + - When receiving / transmitting CAIF Packets (cfpkt), ownership is passed + to the called function (except for framing layers' receive functions + or if a transmit function returns an error, in which case the caller + must free the packet). + +Layered Architecture +-------------------- +The CAIF protocol can be divided into two parts: Support functions and Protocol +Implementation. The support functions include: + + - CFPKT CAIF Packet. Implementation of CAIF Protocol Packet. The + CAIF Packet has functions for creating, destroying and adding content + and for adding/extracting header and trailers to protocol packets. + + - CFLST CAIF list implementation. + + - CFGLUE CAIF Glue. Contains OS Specifics, such as memory + allocation, endianness, etc. + +The CAIF Protocol implementation contains: + + - CFCNFG CAIF Configuration layer. Configures the CAIF Protocol + Stack and provides a Client interface for adding Link-Layer and + Driver interfaces on top of the CAIF Stack. + + - CFCTRL CAIF Control layer. Encodes and Decodes control messages + such as enumeration and channel setup. Also matches request and + response messages. + + - CFSERVL General CAIF Service Layer functionality; handles flow + control and remote shutdown requests. + + - CFVEI CAIF VEI layer. Handles CAIF AT Channels on VEI (Virtual + External Interface). This layer encodes/decodes VEI frames. + + - CFDGML CAIF Datagram layer. Handles CAIF Datagram layer (IP + traffic), encodes/decodes Datagram frames. + + - CFMUX CAIF Mux layer. Handles multiplexing between multiple + physical bearers and multiple channels such as VEI, Datagram, etc. + The MUX keeps track of the existing CAIF Channels and + Physical Instances and selects the apropriate instance based + on Channel-Id and Physical-ID. + + - CFFRML CAIF Framing layer. Handles Framing i.e. Frame length + and frame checksum. + + - CFSERL CAIF Serial layer. Handles concatenation/split of frames + into CAIF Frames with correct length. + + + + +---------+ + | Config | + | CFCNFG | + +---------+ + ! + +---------+ +---------+ +---------+ + | AT | | Control | | Datagram| + | CFVEIL | | CFCTRL | | CFDGML | + +---------+ +---------+ +---------+ + \_____________!______________/ + ! + +---------+ + | MUX | + | | + +---------+ + _____!_____ + / \ + +---------+ +---------+ + | CFFRML | | CFFRML | + | Framing | | Framing | + +---------+ +---------+ + ! ! + +---------+ +---------+ + | | | Serial | + | | | CFSERL | + +---------+ +---------+ + + +In this layered approach the following "rules" apply. + - All layers embed the same structure "struct cflayer" + - A layer does not depend on any other layer's private data. + - Layers are stacked by setting the pointers + layer->up , layer->dn + - In order to send data upwards, each layer should do + layer->up->receive(layer->up, packet); + - In order to send data downwards, each layer should do + layer->dn->transmit(layer->dn, packet); + + +Linux Driver Implementation +=========================== + +Linux GPRS Net Device and CAIF socket are implemented on top of the +CAIF Core protocol. The Net device and CAIF socket have an instance of +'struct cflayer', just like the CAIF Core protocol stack. +Net device and Socket implement the 'receive()' function defined by +'struct cflayer', just like the rest of the CAIF stack. In this way, transmit and +receive of packets is handled as by the rest of the layers: the 'dn->transmit()' +function is called in order to transmit data. + +The layer on top of the CAIF Core implementation is +sometimes referred to as the "Client layer". + + +Configuration of Link Layer +--------------------------- +The Link Layer is implemented as Linux net devices (struct net_device). +Payload handling and registration is done using standard Linux mechanisms. + +The CAIF Protocol relies on a loss-less link layer without implementing +retransmission. This implies that packet drops must not happen. +Therefore a flow-control mechanism is implemented where the physical +interface can initiate flow stop for all CAIF Channels. diff --git a/Documentation/networking/caif/README b/Documentation/networking/caif/README new file mode 100644 index 00000000000..757ccfaa138 --- /dev/null +++ b/Documentation/networking/caif/README @@ -0,0 +1,109 @@ +Copyright (C) ST-Ericsson AB 2010 +Author: Sjur Brendeland/ sjur.brandeland@stericsson.com +License terms: GNU General Public License (GPL) version 2 +--------------------------------------------------------- + +=== Start === +If you have compiled CAIF for modules do: + +$modprobe crc_ccitt +$modprobe caif +$modprobe caif_socket +$modprobe chnl_net + + +=== Preparing the setup with a STE modem === + +If you are working on integration of CAIF you should make sure +that the kernel is built with module support. + +There are some things that need to be tweaked to get the host TTY correctly +set up to talk to the modem. +Since the CAIF stack is running in the kernel and we want to use the existing +TTY, we are installing our physical serial driver as a line discipline above +the TTY device. + +To achieve this we need to install the N_CAIF ldisc from user space. +The benefit is that we can hook up to any TTY. + +The use of Start-of-frame-extension (STX) must also be set as +module parameter "ser_use_stx". + +Normally Frame Checksum is always used on UART, but this is also provided as a +module parameter "ser_use_fcs". + +$ modprobe caif_serial ser_ttyname=/dev/ttyS0 ser_use_stx=yes +$ ifconfig caif_ttyS0 up + +PLEASE NOTE: There is a limitation in Android shell. + It only accepts one argument to insmod/modprobe! + +=== Trouble shooting === + +There are debugfs parameters provided for serial communication. +/sys/kernel/debug/caif_serial/<tty-name>/ + +* ser_state: Prints the bit-mask status where + - 0x02 means SENDING, this is a transient state. + - 0x10 means FLOW_OFF_SENT, i.e. the previous frame has not been sent + and is blocking further send operation. Flow OFF has been propagated + to all CAIF Channels using this TTY. + +* tty_status: Prints the bit-mask tty status information + - 0x01 - tty->warned is on. + - 0x02 - tty->low_latency is on. + - 0x04 - tty->packed is on. + - 0x08 - tty->flow_stopped is on. + - 0x10 - tty->hw_stopped is on. + - 0x20 - tty->stopped is on. + +* last_tx_msg: Binary blob Prints the last transmitted frame. + This can be printed with + $od --format=x1 /sys/kernel/debug/caif_serial/<tty>/last_rx_msg. + The first two tx messages sent look like this. Note: The initial + byte 02 is start of frame extension (STX) used for re-syncing + upon errors. + + - Enumeration: + 0000000 02 05 00 00 03 01 d2 02 + | | | | | | + STX(1) | | | | + Length(2)| | | + Control Channel(1) + Command:Enumeration(1) + Link-ID(1) + Checksum(2) + - Channel Setup: + 0000000 02 07 00 00 00 21 a1 00 48 df + | | | | | | | | + STX(1) | | | | | | + Length(2)| | | | | + Control Channel(1) + Command:Channel Setup(1) + Channel Type(1) + Priority and Link-ID(1) + Endpoint(1) + Checksum(2) + +* last_rx_msg: Prints the last transmitted frame. + The RX messages for LinkSetup look almost identical but they have the + bit 0x20 set in the command bit, and Channel Setup has added one byte + before Checksum containing Channel ID. + NOTE: Several CAIF Messages might be concatenated. The maximum debug + buffer size is 128 bytes. + +== Error Scenarios: +- last_tx_msg contains channel setup message and last_rx_msg is empty -> + The host seems to be able to send over the UART, at least the CAIF ldisc get + notified that sending is completed. + +- last_tx_msg contains enumeration message and last_rx_msg is empty -> + The host is not able to send the message from UART, the tty has not been + able to complete the transmit operation. + +- if /sys/kernel/debug/caif_serial/<tty>/tty_status is non-zero there + might be problems transmitting over UART. + E.g. host and modem wiring is not correct you will typically see + tty_status = 0x10 (hw_stopped) and ser_state = 0x10 (FLOW_OFF_SENT). + You will probably see the enumeration message in last_tx_message + and empty last_rx_message. diff --git a/Documentation/networking/l2tp.txt b/Documentation/networking/l2tp.txt index 63214b280e0..e7bf3979fac 100644 --- a/Documentation/networking/l2tp.txt +++ b/Documentation/networking/l2tp.txt @@ -1,44 +1,95 @@ -This brief document describes how to use the kernel's PPPoL2TP driver -to provide L2TP functionality. L2TP is a protocol that tunnels one or -more PPP sessions over a UDP tunnel. It is commonly used for VPNs +This document describes how to use the kernel's L2TP drivers to +provide L2TP functionality. L2TP is a protocol that tunnels one or +more sessions over an IP tunnel. It is commonly used for VPNs (L2TP/IPSec) and by ISPs to tunnel subscriber PPP sessions over an IP -network infrastructure. +network infrastructure. With L2TPv3, it is also useful as a Layer-2 +tunneling infrastructure. + +Features +======== + +L2TPv2 (PPP over L2TP (UDP tunnels)). +L2TPv3 ethernet pseudowires. +L2TPv3 PPP pseudowires. +L2TPv3 IP encapsulation. +Netlink sockets for L2TPv3 configuration management. + +History +======= + +The original pppol2tp driver was introduced in 2.6.23 and provided +L2TPv2 functionality (rfc2661). L2TPv2 is used to tunnel one or more PPP +sessions over a UDP tunnel. + +L2TPv3 (rfc3931) changes the protocol to allow different frame types +to be passed over an L2TP tunnel by moving the PPP-specific parts of +the protocol out of the core L2TP packet headers. Each frame type is +known as a pseudowire type. Ethernet, PPP, HDLC, Frame Relay and ATM +pseudowires for L2TP are defined in separate RFC standards. Another +change for L2TPv3 is that it can be carried directly over IP with no +UDP header (UDP is optional). It is also possible to create static +unmanaged L2TPv3 tunnels manually without a control protocol +(userspace daemon) to manage them. + +To support L2TPv3, the original pppol2tp driver was split up to +separate the L2TP and PPP functionality. Existing L2TPv2 userspace +apps should be unaffected as the original pppol2tp sockets API is +retained. L2TPv3, however, uses netlink to manage L2TPv3 tunnels and +sessions. Design ====== -The PPPoL2TP driver, drivers/net/pppol2tp.c, provides a mechanism by -which PPP frames carried through an L2TP session are passed through -the kernel's PPP subsystem. The standard PPP daemon, pppd, handles all -PPP interaction with the peer. PPP network interfaces are created for -each local PPP endpoint. - -The L2TP protocol http://www.faqs.org/rfcs/rfc2661.html defines L2TP -control and data frames. L2TP control frames carry messages between -L2TP clients/servers and are used to setup / teardown tunnels and -sessions. An L2TP client or server is implemented in userspace and -will use a regular UDP socket per tunnel. L2TP data frames carry PPP -frames, which may be PPP control or PPP data. The kernel's PPP +The L2TP protocol separates control and data frames. The L2TP kernel +drivers handle only L2TP data frames; control frames are always +handled by userspace. L2TP control frames carry messages between L2TP +clients/servers and are used to setup / teardown tunnels and +sessions. An L2TP client or server is implemented in userspace. + +Each L2TP tunnel is implemented using a UDP or L2TPIP socket; L2TPIP +provides L2TPv3 IP encapsulation (no UDP) and is implemented using a +new l2tpip socket family. The tunnel socket is typically created by +userspace, though for unmanaged L2TPv3 tunnels, the socket can also be +created by the kernel. Each L2TP session (pseudowire) gets a network +interface instance. In the case of PPP, these interfaces are created +indirectly by pppd using a pppol2tp socket. In the case of ethernet, +the netdevice is created upon a netlink request to create an L2TPv3 +ethernet pseudowire. + +For PPP, the PPPoL2TP driver, net/l2tp/l2tp_ppp.c, provides a +mechanism by which PPP frames carried through an L2TP session are +passed through the kernel's PPP subsystem. The standard PPP daemon, +pppd, handles all PPP interaction with the peer. PPP network +interfaces are created for each local PPP endpoint. The kernel's PPP subsystem arranges for PPP control frames to be delivered to pppd, while data frames are forwarded as usual. +For ethernet, the L2TPETH driver, net/l2tp/l2tp_eth.c, implements a +netdevice driver, managing virtual ethernet devices, one per +pseudowire. These interfaces can be managed using standard Linux tools +such as "ip" and "ifconfig". If only IP frames are passed over the +tunnel, the interface can be given an IP addresses of itself and its +peer. If non-IP frames are to be passed over the tunnel, the interface +can be added to a bridge using brctl. All L2TP datapath protocol +functions are handled by the L2TP core driver. + Each tunnel and session within a tunnel is assigned a unique tunnel_id and session_id. These ids are carried in the L2TP header of every -control and data packet. The pppol2tp driver uses them to lookup -internal tunnel and/or session contexts. Zero tunnel / session ids are -treated specially - zero ids are never assigned to tunnels or sessions -in the network. In the driver, the tunnel context keeps a pointer to -the tunnel UDP socket. The session context keeps a pointer to the -PPPoL2TP socket, as well as other data that lets the driver interface -to the kernel PPP subsystem. - -Note that the pppol2tp kernel driver handles only L2TP data frames; -L2TP control frames are simply passed up to userspace in the UDP -tunnel socket. The kernel handles all datapath aspects of the -protocol, including data packet resequencing (if enabled). - -There are a number of requirements on the userspace L2TP daemon in -order to use the pppol2tp driver. +control and data packet. (Actually, in L2TPv3, the tunnel_id isn't +present in data frames - it is inferred from the IP connection on +which the packet was received.) The L2TP driver uses the ids to lookup +internal tunnel and/or session contexts to determine how to handle the +packet. Zero tunnel / session ids are treated specially - zero ids are +never assigned to tunnels or sessions in the network. In the driver, +the tunnel context keeps a reference to the tunnel UDP or L2TPIP +socket. The session context holds data that lets the driver interface +to the kernel's network frame type subsystems, i.e. PPP, ethernet. + +Userspace Programming +===================== + +For L2TPv2, there are a number of requirements on the userspace L2TP +daemon in order to use the pppol2tp driver. 1. Use a UDP socket per tunnel. @@ -86,6 +137,35 @@ In addition to the standard PPP ioctls, a PPPIOCGL2TPSTATS is provided to retrieve tunnel and session statistics from the kernel using the PPPoX socket of the appropriate tunnel or session. +For L2TPv3, userspace must use the netlink API defined in +include/linux/l2tp.h to manage tunnel and session contexts. The +general procedure to create a new L2TP tunnel with one session is:- + +1. Open a GENL socket using L2TP_GENL_NAME for configuring the kernel + using netlink. + +2. Create a UDP or L2TPIP socket for the tunnel. + +3. Create a new L2TP tunnel using a L2TP_CMD_TUNNEL_CREATE + request. Set attributes according to desired tunnel parameters, + referencing the UDP or L2TPIP socket created in the previous step. + +4. Create a new L2TP session in the tunnel using a + L2TP_CMD_SESSION_CREATE request. + +The tunnel and all of its sessions are closed when the tunnel socket +is closed. The netlink API may also be used to delete sessions and +tunnels. Configuration and status info may be set or read using netlink. + +The L2TP driver also supports static (unmanaged) L2TPv3 tunnels. These +are where there is no L2TP control message exchange with the peer to +setup the tunnel; the tunnel is configured manually at each end of the +tunnel. There is no need for an L2TP userspace application in this +case -- the tunnel socket is created by the kernel and configured +using parameters sent in the L2TP_CMD_TUNNEL_CREATE netlink +request. The "ip" utility of iproute2 has commands for managing static +L2TPv3 tunnels; do "ip l2tp help" for more information. + Debugging ========= @@ -102,6 +182,69 @@ PPPOL2TP_MSG_CONTROL userspace - kernel interface PPPOL2TP_MSG_SEQ sequence numbers handling PPPOL2TP_MSG_DATA data packets +If enabled, files under a l2tp debugfs directory can be used to dump +kernel state about L2TP tunnels and sessions. To access it, the +debugfs filesystem must first be mounted. + +# mount -t debugfs debugfs /debug + +Files under the l2tp directory can then be accessed. + +# cat /debug/l2tp/tunnels + +The debugfs files should not be used by applications to obtain L2TP +state information because the file format is subject to change. It is +implemented to provide extra debug information to help diagnose +problems.) Users should use the netlink API. + +/proc/net/pppol2tp is also provided for backwards compaibility with +the original pppol2tp driver. It lists information about L2TPv2 +tunnels and sessions only. Its use is discouraged. + +Unmanaged L2TPv3 Tunnels +======================== + +Some commercial L2TP products support unmanaged L2TPv3 ethernet +tunnels, where there is no L2TP control protocol; tunnels are +configured at each side manually. New commands are available in +iproute2's ip utility to support this. + +To create an L2TPv3 ethernet pseudowire between local host 192.168.1.1 +and peer 192.168.1.2, using IP addresses 10.5.1.1 and 10.5.1.2 for the +tunnel endpoints:- + +# modprobe l2tp_eth +# modprobe l2tp_netlink + +# ip l2tp add tunnel tunnel_id 1 peer_tunnel_id 1 udp_sport 5000 \ + udp_dport 5000 encap udp local 192.168.1.1 remote 192.168.1.2 +# ip l2tp add session tunnel_id 1 session_id 1 peer_session_id 1 +# ifconfig -a +# ip addr add 10.5.1.2/32 peer 10.5.1.1/32 dev l2tpeth0 +# ifconfig l2tpeth0 up + +Choose IP addresses to be the address of a local IP interface and that +of the remote system. The IP addresses of the l2tpeth0 interface can be +anything suitable. + +Repeat the above at the peer, with ports, tunnel/session ids and IP +addresses reversed. The tunnel and session IDs can be any non-zero +32-bit number, but the values must be reversed at the peer. + +Host 1 Host2 +udp_sport=5000 udp_sport=5001 +udp_dport=5001 udp_dport=5000 +tunnel_id=42 tunnel_id=45 +peer_tunnel_id=45 peer_tunnel_id=42 +session_id=128 session_id=5196755 +peer_session_id=5196755 peer_session_id=128 + +When done at both ends of the tunnel, it should be possible to send +data over the network. e.g. + +# ping 10.5.1.1 + + Sample Userspace Code ===================== @@ -158,12 +301,48 @@ Sample Userspace Code } return 0; +Internal Implementation +======================= + +The driver keeps a struct l2tp_tunnel context per L2TP tunnel and a +struct l2tp_session context for each session. The l2tp_tunnel is +always associated with a UDP or L2TP/IP socket and keeps a list of +sessions in the tunnel. The l2tp_session context keeps kernel state +about the session. It has private data which is used for data specific +to the session type. With L2TPv2, the session always carried PPP +traffic. With L2TPv3, the session can also carry ethernet frames +(ethernet pseudowire) or other data types such as ATM, HDLC or Frame +Relay. + +When a tunnel is first opened, the reference count on the socket is +increased using sock_hold(). This ensures that the kernel socket +cannot be removed while L2TP's data structures reference it. + +Some L2TP sessions also have a socket (PPP pseudowires) while others +do not (ethernet pseudowires). We can't use the socket reference count +as the reference count for session contexts. The L2TP implementation +therefore has its own internal reference counts on the session +contexts. + +To Do +===== + +Add L2TP tunnel switching support. This would route tunneled traffic +from one L2TP tunnel into another. Specified in +http://tools.ietf.org/html/draft-ietf-l2tpext-tunnel-switching-08 + +Add L2TPv3 VLAN pseudowire support. + +Add L2TPv3 IP pseudowire support. + +Add L2TPv3 ATM pseudowire support. + Miscellaneous -============ +============= -The PPPoL2TP driver was developed as part of the OpenL2TP project by +The L2TP drivers were developed as part of the OpenL2TP project by Katalix Systems Ltd. OpenL2TP is a full-featured L2TP client / server, designed from the ground up to have the L2TP datapath in the kernel. The project also implemented the pppol2tp plugin for pppd which allows pppd to use the kernel driver. Details can be found at -http://openl2tp.sourceforge.net. +http://www.openl2tp.org. diff --git a/Documentation/networking/stmmac.txt b/Documentation/networking/stmmac.txt new file mode 100644 index 00000000000..7ee770b5ef5 --- /dev/null +++ b/Documentation/networking/stmmac.txt @@ -0,0 +1,143 @@ + STMicroelectronics 10/100/1000 Synopsys Ethernet driver + +Copyright (C) 2007-2010 STMicroelectronics Ltd +Author: Giuseppe Cavallaro <peppe.cavallaro@st.com> + +This is the driver for the MAC 10/100/1000 on-chip Ethernet controllers +(Synopsys IP blocks); it has been fully tested on STLinux platforms. + +Currently this network device driver is for all STM embedded MAC/GMAC +(7xxx SoCs). + +DWC Ether MAC 10/100/1000 Universal version 3.41a and DWC Ether MAC 10/100 +Universal version 4.0 have been used for developing the first code +implementation. + +Please, for more information also visit: www.stlinux.com + +1) Kernel Configuration +The kernel configuration option is STMMAC_ETH: + Device Drivers ---> Network device support ---> Ethernet (1000 Mbit) ---> + STMicroelectronics 10/100/1000 Ethernet driver (STMMAC_ETH) + +2) Driver parameters list: + debug: message level (0: no output, 16: all); + phyaddr: to manually provide the physical address to the PHY device; + dma_rxsize: DMA rx ring size; + dma_txsize: DMA tx ring size; + buf_sz: DMA buffer size; + tc: control the HW FIFO threshold; + tx_coe: Enable/Disable Tx Checksum Offload engine; + watchdog: transmit timeout (in milliseconds); + flow_ctrl: Flow control ability [on/off]; + pause: Flow Control Pause Time; + tmrate: timer period (only if timer optimisation is configured). + +3) Command line options +Driver parameters can be also passed in command line by using: + stmmaceth=dma_rxsize:128,dma_txsize:512 + +4) Driver information and notes + +4.1) Transmit process +The xmit method is invoked when the kernel needs to transmit a packet; it sets +the descriptors in the ring and informs the DMA engine that there is a packet +ready to be transmitted. +Once the controller has finished transmitting the packet, an interrupt is +triggered; So the driver will be able to release the socket buffers. +By default, the driver sets the NETIF_F_SG bit in the features field of the +net_device structure enabling the scatter/gather feature. + +4.2) Receive process +When one or more packets are received, an interrupt happens. The interrupts +are not queued so the driver has to scan all the descriptors in the ring during +the receive process. +This is based on NAPI so the interrupt handler signals only if there is work to be +done, and it exits. +Then the poll method will be scheduled at some future point. +The incoming packets are stored, by the DMA, in a list of pre-allocated socket +buffers in order to avoid the memcpy (Zero-copy). + +4.3) Timer-Driver Interrupt +Instead of having the device that asynchronously notifies the frame receptions, the +driver configures a timer to generate an interrupt at regular intervals. +Based on the granularity of the timer, the frames that are received by the device +will experience different levels of latency. Some NICs have dedicated timer +device to perform this task. STMMAC can use either the RTC device or the TMU +channel 2 on STLinux platforms. +The timers frequency can be passed to the driver as parameter; when change it, +take care of both hardware capability and network stability/performance impact. +Several performance tests on STM platforms showed this optimisation allows to spare +the CPU while having the maximum throughput. + +4.4) WOL +Wake up on Lan feature through Magic Frame is only supported for the GMAC +core. + +4.5) DMA descriptors +Driver handles both normal and enhanced descriptors. The latter has been only +tested on DWC Ether MAC 10/100/1000 Universal version 3.41a. + +4.6) Ethtool support +Ethtool is supported. Driver statistics and internal errors can be taken using: +ethtool -S ethX command. It is possible to dump registers etc. + +4.7) Jumbo and Segmentation Offloading +Jumbo frames are supported and tested for the GMAC. +The GSO has been also added but it's performed in software. +LRO is not supported. + +4.8) Physical +The driver is compatible with PAL to work with PHY and GPHY devices. + +4.9) Platform information +Several information came from the platform; please refer to the +driver's Header file in include/linux directory. + +struct plat_stmmacenet_data { + int bus_id; + int pbl; + int has_gmac; + void (*fix_mac_speed)(void *priv, unsigned int speed); + void (*bus_setup)(unsigned long ioaddr); +#ifdef CONFIG_STM_DRIVERS + struct stm_pad_config *pad_config; +#endif + void *bsp_priv; +}; + +Where: +- pbl (Programmable Burst Length) is maximum number of + beats to be transferred in one DMA transaction. + GMAC also enables the 4xPBL by default. +- fix_mac_speed and bus_setup are used to configure internal target + registers (on STM platforms); +- has_gmac: GMAC core is on board (get it at run-time in the next step); +- bus_id: bus identifier. + +struct plat_stmmacphy_data { + int bus_id; + int phy_addr; + unsigned int phy_mask; + int interface; + int (*phy_reset)(void *priv); + void *priv; +}; + +Where: +- bus_id: bus identifier; +- phy_addr: physical address used for the attached phy device; + set it to -1 to get it at run-time; +- interface: physical MII interface mode; +- phy_reset: hook to reset HW function. + +TODO: +- Continue to make the driver more generic and suitable for other Synopsys + Ethernet controllers used on other architectures (i.e. ARM). +- 10G controllers are not supported. +- MAC uses Normal descriptors and GMAC uses enhanced ones. + This is a limit that should be reviewed. MAC could want to + use the enhanced structure. +- Checksumming: Rx/Tx csum is done in HW in case of GMAC only. +- Review the timer optimisation code to use an embedded device that seems to be + available in new chip generations. diff --git a/Documentation/networking/timestamping.txt b/Documentation/networking/timestamping.txt index 0e58b453917..e8c8f4f06c6 100644 --- a/Documentation/networking/timestamping.txt +++ b/Documentation/networking/timestamping.txt @@ -41,11 +41,12 @@ SOF_TIMESTAMPING_SOFTWARE: return system time stamp generated in SOF_TIMESTAMPING_TX/RX determine how time stamps are generated. SOF_TIMESTAMPING_RAW/SYS determine how they are reported in the following control message: - struct scm_timestamping { - struct timespec systime; - struct timespec hwtimetrans; - struct timespec hwtimeraw; - }; + +struct scm_timestamping { + struct timespec systime; + struct timespec hwtimetrans; + struct timespec hwtimeraw; +}; recvmsg() can be used to get this control message for regular incoming packets. For send time stamps the outgoing packet is looped back to @@ -87,12 +88,13 @@ by the network device and will be empty without that support. SIOCSHWTSTAMP: Hardware time stamping must also be initialized for each device driver -that is expected to do hardware time stamping. The parameter is: +that is expected to do hardware time stamping. The parameter is defined in +/include/linux/net_tstamp.h as: struct hwtstamp_config { - int flags; /* no flags defined right now, must be zero */ - int tx_type; /* HWTSTAMP_TX_* */ - int rx_filter; /* HWTSTAMP_FILTER_* */ + int flags; /* no flags defined right now, must be zero */ + int tx_type; /* HWTSTAMP_TX_* */ + int rx_filter; /* HWTSTAMP_FILTER_* */ }; Desired behavior is passed into the kernel and to a specific device by @@ -139,42 +141,56 @@ enum { /* time stamp any incoming packet */ HWTSTAMP_FILTER_ALL, - /* return value: time stamp all packets requested plus some others */ - HWTSTAMP_FILTER_SOME, + /* return value: time stamp all packets requested plus some others */ + HWTSTAMP_FILTER_SOME, /* PTP v1, UDP, any kind of event packet */ HWTSTAMP_FILTER_PTP_V1_L4_EVENT, - ... + /* for the complete list of values, please check + * the include file /include/linux/net_tstamp.h + */ }; DEVICE IMPLEMENTATION A driver which supports hardware time stamping must support the -SIOCSHWTSTAMP ioctl. Time stamps for received packets must be stored -in the skb with skb_hwtstamp_set(). +SIOCSHWTSTAMP ioctl and update the supplied struct hwtstamp_config with +the actual values as described in the section on SIOCSHWTSTAMP. + +Time stamps for received packets must be stored in the skb. To get a pointer +to the shared time stamp structure of the skb call skb_hwtstamps(). Then +set the time stamps in the structure: + +struct skb_shared_hwtstamps { + /* hardware time stamp transformed into duration + * since arbitrary point in time + */ + ktime_t hwtstamp; + ktime_t syststamp; /* hwtstamp transformed to system time base */ +}; Time stamps for outgoing packets are to be generated as follows: -- In hard_start_xmit(), check if skb_hwtstamp_check_tx_hardware() - returns non-zero. If yes, then the driver is expected - to do hardware time stamping. +- In hard_start_xmit(), check if skb_tx(skb)->hardware is set no-zero. + If yes, then the driver is expected to do hardware time stamping. - If this is possible for the skb and requested, then declare - that the driver is doing the time stamping by calling - skb_hwtstamp_tx_in_progress(). A driver not supporting - hardware time stamping doesn't do that. A driver must never - touch sk_buff::tstamp! It is used to store how time stamping - for an outgoing packets is to be done. + that the driver is doing the time stamping by setting the field + skb_tx(skb)->in_progress non-zero. You might want to keep a pointer + to the associated skb for the next step and not free the skb. A driver + not supporting hardware time stamping doesn't do that. A driver must + never touch sk_buff::tstamp! It is used to store software generated + time stamps by the network subsystem. - As soon as the driver has sent the packet and/or obtained a hardware time stamp for it, it passes the time stamp back by calling skb_hwtstamp_tx() with the original skb, the raw - hardware time stamp and a handle to the device (necessary - to convert the hardware time stamp to system time). If obtaining - the hardware time stamp somehow fails, then the driver should - not fall back to software time stamping. The rationale is that - this would occur at a later time in the processing pipeline - than other software time stamping and therefore could lead - to unexpected deltas between time stamps. -- If the driver did not call skb_hwtstamp_tx_in_progress(), then + hardware time stamp. skb_hwtstamp_tx() clones the original skb and + adds the timestamps, therefore the original skb has to be freed now. + If obtaining the hardware time stamp somehow fails, then the driver + should not fall back to software time stamping. The rationale is that + this would occur at a later time in the processing pipeline than other + software time stamping and therefore could lead to unexpected deltas + between time stamps. +- If the driver did not call set skb_tx(skb)->in_progress, then dev_hard_start_xmit() checks whether software time stamping is wanted as fallback and potentially generates the time stamp. diff --git a/Documentation/powerpc/dts-bindings/fsl/cpm_qe/qe.txt b/Documentation/powerpc/dts-bindings/fsl/cpm_qe/qe.txt index 6e37be1eeb2..4f8930263dd 100644 --- a/Documentation/powerpc/dts-bindings/fsl/cpm_qe/qe.txt +++ b/Documentation/powerpc/dts-bindings/fsl/cpm_qe/qe.txt @@ -21,6 +21,15 @@ Required properties: - fsl,qe-num-snums: define how many serial number(SNUM) the QE can use for the threads. +Optional properties: +- fsl,firmware-phandle: + Usage: required only if there is no fsl,qe-firmware child node + Value type: <phandle> + Definition: Points to a firmware node (see "QE Firmware Node" below) + that contains the firmware that should be uploaded for this QE. + The compatible property for the firmware node should say, + "fsl,qe-firmware". + Recommended properties - brg-frequency : the internal clock source frequency for baud-rate generators in Hz. @@ -59,3 +68,48 @@ Example: reg = <0 c000>; }; }; + +* QE Firmware Node + +This node defines a firmware binary that is embedded in the device tree, for +the purpose of passing the firmware from bootloader to the kernel, or from +the hypervisor to the guest. + +The firmware node itself contains the firmware binary contents, a compatible +property, and any firmware-specific properties. The node should be placed +inside a QE node that needs it. Doing so eliminates the need for a +fsl,firmware-phandle property. Other QE nodes that need the same firmware +should define an fsl,firmware-phandle property that points to the firmware node +in the first QE node. + +The fsl,firmware property can be specified in the DTS (possibly using incbin) +or can be inserted by the boot loader at boot time. + +Required properties: + - compatible + Usage: required + Value type: <string> + Definition: A standard property. Specify a string that indicates what + kind of firmware it is. For QE, this should be "fsl,qe-firmware". + + - fsl,firmware + Usage: required + Value type: <prop-encoded-array>, encoded as an array of bytes + Definition: A standard property. This property contains the firmware + binary "blob". + +Example: + qe1@e0080000 { + compatible = "fsl,qe"; + qe_firmware:qe-firmware { + compatible = "fsl,qe-firmware"; + fsl,firmware = [0x70 0xcd 0x00 0x00 0x01 0x46 0x45 ...]; + }; + ... + }; + + qe2@e0090000 { + compatible = "fsl,qe"; + fsl,firmware-phandle = <&qe_firmware>; + ... + }; diff --git a/Documentation/rfkill.txt b/Documentation/rfkill.txt index b4860509c31..83668e5dd17 100644 --- a/Documentation/rfkill.txt +++ b/Documentation/rfkill.txt @@ -99,37 +99,15 @@ system. Also, it is possible to switch all rfkill drivers (or all drivers of a specified type) into a state which also updates the default state for hotplugged devices. -After an application opens /dev/rfkill, it can read the current state of -all devices, and afterwards can poll the descriptor for hotplug or state -change events. - -Applications must ignore operations (the "op" field) they do not handle, -this allows the API to be extended in the future. - -Additionally, each rfkill device is registered in sysfs and there has the -following attributes: - - name: Name assigned by driver to this key (interface or driver name). - type: Driver type string ("wlan", "bluetooth", etc). - persistent: Whether the soft blocked state is initialised from - non-volatile storage at startup. - state: Current state of the transmitter - 0: RFKILL_STATE_SOFT_BLOCKED - transmitter is turned off by software - 1: RFKILL_STATE_UNBLOCKED - transmitter is (potentially) active - 2: RFKILL_STATE_HARD_BLOCKED - transmitter is forced off by something outside of - the driver's control. - This file is deprecated because it can only properly show - three of the four possible states, soft-and-hard-blocked is - missing. - claim: 0: Kernel handles events - This file is deprecated because there no longer is a way to - claim just control over a single rfkill instance. - -rfkill devices also issue uevents (with an action of "change"), with the -following environment variables set: +After an application opens /dev/rfkill, it can read the current state of all +devices. Changes can be either obtained by either polling the descriptor for +hotplug or state change events or by listening for uevents emitted by the +rfkill core framework. + +Additionally, each rfkill device is registered in sysfs and emits uevents. + +rfkill devices issue uevents (with an action of "change"), with the following +environment variables set: RFKILL_NAME RFKILL_STATE @@ -137,3 +115,7 @@ RFKILL_TYPE The contents of these variables corresponds to the "name", "state" and "type" sysfs files explained above. + + +For further details consult Documentation/ABI/stable/dev-rfkill and +Documentation/ABI/stable/sysfs-class-rfkill. diff --git a/Documentation/sound/alsa/HD-Audio.txt b/Documentation/sound/alsa/HD-Audio.txt index f4dd3bf99d1..98d14cb8a85 100644 --- a/Documentation/sound/alsa/HD-Audio.txt +++ b/Documentation/sound/alsa/HD-Audio.txt @@ -119,10 +119,18 @@ the codec slots 0 and 1 no matter what the hardware reports. Interrupt Handling ~~~~~~~~~~~~~~~~~~ -In rare but some cases, the interrupt isn't properly handled as -default. You would notice this by the DMA transfer error reported by -ALSA PCM core, for example. Using MSI might help in such a case. -Pass `enable_msi=1` option for enabling MSI. +HD-audio driver uses MSI as default (if available) since 2.6.33 +kernel as MSI works better on some machines, and in general, it's +better for performance. However, Nvidia controllers showed bad +regressions with MSI (especially in a combination with AMD chipset), +thus we disabled MSI for them. + +There seem also still other devices that don't work with MSI. If you +see a regression wrt the sound quality (stuttering, etc) or a lock-up +in the recent kernel, try to pass `enable_msi=0` option to disable +MSI. If it works, you can add the known bad device to the blacklist +defined in hda_intel.c. In such a case, please report and give the +patch back to the upstream developer. HD-AUDIO CODEC diff --git a/Documentation/volatile-considered-harmful.txt b/Documentation/volatile-considered-harmful.txt index 991c26a6ef6..db0cb228d64 100644 --- a/Documentation/volatile-considered-harmful.txt +++ b/Documentation/volatile-considered-harmful.txt @@ -63,9 +63,9 @@ way to perform a busy wait is: cpu_relax(); The cpu_relax() call can lower CPU power consumption or yield to a -hyperthreaded twin processor; it also happens to serve as a memory barrier, -so, once again, volatile is unnecessary. Of course, busy-waiting is -generally an anti-social act to begin with. +hyperthreaded twin processor; it also happens to serve as a compiler +barrier, so, once again, volatile is unnecessary. Of course, busy- +waiting is generally an anti-social act to begin with. There are still a few rare situations where volatile makes sense in the kernel: diff --git a/Documentation/watchdog/src/watchdog-simple.c b/Documentation/watchdog/src/watchdog-simple.c index 4cf72f3fa8e..ba45803a221 100644 --- a/Documentation/watchdog/src/watchdog-simple.c +++ b/Documentation/watchdog/src/watchdog-simple.c @@ -17,9 +17,6 @@ int main(void) ret = -1; break; } - ret = fsync(fd); - if (ret) - break; sleep(10); } close(fd); diff --git a/Documentation/watchdog/src/watchdog-test.c b/Documentation/watchdog/src/watchdog-test.c index a750532ffcf..63fdc34ceb9 100644 --- a/Documentation/watchdog/src/watchdog-test.c +++ b/Documentation/watchdog/src/watchdog-test.c @@ -31,6 +31,8 @@ static void keep_alive(void) */ int main(int argc, char *argv[]) { + int flags; + fd = open("/dev/watchdog", O_WRONLY); if (fd == -1) { @@ -41,12 +43,14 @@ int main(int argc, char *argv[]) if (argc > 1) { if (!strncasecmp(argv[1], "-d", 2)) { - ioctl(fd, WDIOC_SETOPTIONS, WDIOS_DISABLECARD); + flags = WDIOS_DISABLECARD; + ioctl(fd, WDIOC_SETOPTIONS, &flags); fprintf(stderr, "Watchdog card disabled.\n"); fflush(stderr); exit(0); } else if (!strncasecmp(argv[1], "-e", 2)) { - ioctl(fd, WDIOC_SETOPTIONS, WDIOS_ENABLECARD); + flags = WDIOS_ENABLECARD; + ioctl(fd, WDIOC_SETOPTIONS, &flags); fprintf(stderr, "Watchdog card enabled.\n"); fflush(stderr); exit(0); diff --git a/Documentation/watchdog/watchdog-api.txt b/Documentation/watchdog/watchdog-api.txt index 4cc4ba9d715..eb7132ed8bb 100644 --- a/Documentation/watchdog/watchdog-api.txt +++ b/Documentation/watchdog/watchdog-api.txt @@ -222,11 +222,10 @@ returned value is the temperature in degrees fahrenheit. ioctl(fd, WDIOC_GETTEMP, &temperature); Finally the SETOPTIONS ioctl can be used to control some aspects of -the cards operation; right now the pcwd driver is the only one -supporting this ioctl. +the cards operation. int options = 0; - ioctl(fd, WDIOC_SETOPTIONS, options); + ioctl(fd, WDIOC_SETOPTIONS, &options); The following options are available: |