11 files changed, 881 insertions, 171 deletions

diff --git a/Documentation/feature-removal-schedule.txt b/Documentation/feature-removal-schedule.txt
index 46ece3fba6f9..8319c462c9f0 100644
--- a/Documentation/feature-removal-schedule.txt
+++ b/Documentation/feature-removal-schedule.txt
@@ -315,6 +315,18 @@ Who:	Matthew Wilcox <willy@linux.intel.com>
 
 ---------------------------
 
+What:   SCTP_GET_PEER_ADDRS_NUM_OLD, SCTP_GET_PEER_ADDRS_OLD,
+        SCTP_GET_LOCAL_ADDRS_NUM_OLD, SCTP_GET_LOCAL_ADDRS_OLD
+When:   June 2009
+Why:    A newer version of the options have been introduced in 2005 that
+        removes the limitions of the old API.  The sctp library has been
+        converted to use these new options at the same time.  Any user
+        space app that directly uses the old options should convert to using
+        the new options.
+Who:    Vlad Yasevich <vladislav.yasevich@hp.com>
+
+---------------------------
+
 What:   CONFIG_THERMAL_HWMON
 When:   January 2009
 Why:    This option was introduced just to allow older lm-sensors userspace
diff --git a/Documentation/networking/bonding.txt b/Documentation/networking/bonding.txt
index a0cda062bc33..7fa7fe71d7a8 100644
--- a/Documentation/networking/bonding.txt
+++ b/Documentation/networking/bonding.txt
@@ -289,35 +289,73 @@ downdelay
 fail_over_mac
 
         Specifies whether active-backup mode should set all slaves to
-        the same MAC address (the traditional behavior), or, when
-        enabled, change the bond's MAC address when changing the
-        active interface (i.e., fail over the MAC address itself).
-
-        Fail over MAC is useful for devices that cannot ever alter
-        their MAC address, or for devices that refuse incoming
-        broadcasts with their own source MAC (which interferes with
-        the ARP monitor).
-
-        The down side of fail over MAC is that every device on the
-        network must be updated via gratuitous ARP, vs. just updating
-        a switch or set of switches (which often takes place for any
-        traffic, not just ARP traffic, if the switch snoops incoming
-        traffic to update its tables) for the traditional method.  If
-        the gratuitous ARP is lost, communication may be disrupted.
-
-        When fail over MAC is used in conjuction with the mii monitor,
-        devices which assert link up prior to being able to actually
-        transmit and receive are particularly susecptible to loss of
-        the gratuitous ARP, and an appropriate updelay setting may be
-        required.
-
-        A value of 0 disables fail over MAC, and is the default.  A
-        value of 1 enables fail over MAC.  This option is enabled
-        automatically if the first slave added cannot change its MAC
-        address.  This option may be modified via sysfs only when no
-        slaves are present in the bond.
-
-        This option was added in bonding version 3.2.0.
+        the same MAC address at enslavement (the traditional
+        behavior), or, when enabled, perform special handling of the
+        bond's MAC address in accordance with the selected policy.
+
+        Possible values are:
+
+        none or 0
+
+                This setting disables fail_over_mac, and causes
+                bonding to set all slaves of an active-backup bond to
+                the same MAC address at enslavement time.  This is the
+                default.
+
+        active or 1
+
+                The "active" fail_over_mac policy indicates that the
+                MAC address of the bond should always be the MAC
+                address of the currently active slave.  The MAC
+                address of the slaves is not changed; instead, the MAC
+                address of the bond changes during a failover.
+
+                This policy is useful for devices that cannot ever
+                alter their MAC address, or for devices that refuse
+                incoming broadcasts with their own source MAC (which
+                interferes with the ARP monitor).
+
+                The down side of this policy is that every device on
+                the network must be updated via gratuitous ARP,
+                vs. just updating a switch or set of switches (which
+                often takes place for any traffic, not just ARP
+                traffic, if the switch snoops incoming traffic to
+                update its tables) for the traditional method.  If the
+                gratuitous ARP is lost, communication may be
+                disrupted.
+
+                When this policy is used in conjuction with the mii
+                monitor, devices which assert link up prior to being
+                able to actually transmit and receive are particularly
+                susecptible to loss of the gratuitous ARP, and an
+                appropriate updelay setting may be required.
+
+        follow or 2
+
+                The "follow" fail_over_mac policy causes the MAC
+                address of the bond to be selected normally (normally
+                the MAC address of the first slave added to the bond).
+                However, the second and subsequent slaves are not set
+                to this MAC address while they are in a backup role; a
+                slave is programmed with the bond's MAC address at
+                failover time (and the formerly active slave receives
+                the newly active slave's MAC address).
+
+                This policy is useful for multiport devices that
+                either become confused or incur a performance penalty
+                when multiple ports are programmed with the same MAC
+                address.
+
+
+        The default policy is none, unless the first slave cannot
+        change its MAC address, in which case the active policy is
+        selected by default.
+
+        This option may be modified via sysfs only when no slaves are
+        present in the bond.
+
+        This option was added in bonding version 3.2.0.  The "follow"
+        policy was added in bonding version 3.3.0.
 
 lacp_rate
 
@@ -338,7 +376,8 @@ max_bonds
         Specifies the number of bonding devices to create for this
         instance of the bonding driver.  E.g., if max_bonds is 3, and
         the bonding driver is not already loaded, then bond0, bond1
-        and bond2 will be created.  The default value is 1.
+        and bond2 will be created.  The default value is 1.  Specifying
+        a value of 0 will load bonding, but will not create any devices.
 
 miimon
 
@@ -501,6 +540,17 @@ mode
                 swapped with the new curr_active_slave that was
                 chosen.
 
+num_grat_arp
+
+        Specifies the number of gratuitous ARPs to be issued after a
+        failover event.  One gratuitous ARP is issued immediately after
+        the failover, subsequent ARPs are sent at a rate of one per link
+        monitor interval (arp_interval or miimon, whichever is active).
+
+        The valid range is 0 - 255; the default value is 1.  This option
+        affects only the active-backup mode.  This option was added for
+        bonding version 3.3.0.
+
 primary
 
         A string (eth0, eth2, etc) specifying which slave is the
diff --git a/Documentation/networking/dm9000.txt b/Documentation/networking/dm9000.txt
new file mode 100644
index 000000000000..65df3dea5561
--- /dev/null
+++ b/Documentation/networking/dm9000.txt
@@ -0,0 +1,167 @@
+DM9000 Network driver
+=====================
+
+Copyright 2008 Simtec Electronics,
+          Ben Dooks <ben@simtec.co.uk> <ben-linux@fluff.org>
+
+
+Introduction
+------------
+
+This file describes how to use the DM9000 platform-device based network driver
+that is contained in the files drivers/net/dm9000.c and drivers/net/dm9000.h.
+
+The driver supports three DM9000 variants, the DM9000E which is the first chip
+supported as well as the newer DM9000A and DM9000B devices. It is currently
+maintained and tested by Ben Dooks, who should be CC: to any patches for this
+driver.
+
+
+Defining the platform device
+----------------------------
+
+The minimum set of resources attached to the platform device are as follows:
+
+    1) The physical address of the address register
+    2) The physical address of the data register
+    3) The IRQ line the device's interrupt pin is connected to.
+
+These resources should be specified in that order, as the ordering of the
+two address regions is important (the driver expects these to be address
+and then data).
+
+An example from arch/arm/mach-s3c2410/mach-bast.c is:
+
+static struct resource bast_dm9k_resource[] = {
+        [0] = {
+                .start = S3C2410_CS5 + BAST_PA_DM9000,
+                .end   = S3C2410_CS5 + BAST_PA_DM9000 + 3,
+                .flags = IORESOURCE_MEM,
+        },
+        [1] = {
+                .start = S3C2410_CS5 + BAST_PA_DM9000 + 0x40,
+                .end   = S3C2410_CS5 + BAST_PA_DM9000 + 0x40 + 0x3f,
+                .flags = IORESOURCE_MEM,
+        },
+        [2] = {
+                .start = IRQ_DM9000,
+                .end   = IRQ_DM9000,
+                .flags = IORESOURCE_IRQ | IORESOURCE_IRQ_HIGHLEVEL,
+        }
+};
+
+static struct platform_device bast_device_dm9k = {
+        .name           = "dm9000",
+        .id             = 0,
+        .num_resources  = ARRAY_SIZE(bast_dm9k_resource),
+        .resource       = bast_dm9k_resource,
+};
+
+Note the setting of the IRQ trigger flag in bast_dm9k_resource[2].flags,
+as this will generate a warning if it is not present. The trigger from
+the flags field will be passed to request_irq() when registering the IRQ
+handler to ensure that the IRQ is setup correctly.
+
+This shows a typical platform device, without the optional configuration
+platform data supplied. The next example uses the same resources, but adds
+the optional platform data to pass extra configuration data:
+
+static struct dm9000_plat_data bast_dm9k_platdata = {
+        .flags          = DM9000_PLATF_16BITONLY,
+};
+
+static struct platform_device bast_device_dm9k = {
+        .name           = "dm9000",
+        .id             = 0,
+        .num_resources  = ARRAY_SIZE(bast_dm9k_resource),
+        .resource       = bast_dm9k_resource,
+        .dev            = {
+                .platform_data = &bast_dm9k_platdata,
+        }
+};
+
+The platform data is defined in include/linux/dm9000.h and described below.
+
+
+Platform data
+-------------
+
+Extra platform data for the DM9000 can describe the IO bus width to the
+device, whether or not an external PHY is attached to the device and
+the availability of an external configuration EEPROM.
+
+The flags for the platform data .flags field are as follows:
+
+DM9000_PLATF_8BITONLY
+
+        The IO should be done with 8bit operations.
+
+DM9000_PLATF_16BITONLY
+
+        The IO should be done with 16bit operations.
+
+DM9000_PLATF_32BITONLY
+
+        The IO should be done with 32bit operations.
+
+DM9000_PLATF_EXT_PHY
+
+        The chip is connected to an external PHY.
+
+DM9000_PLATF_NO_EEPROM
+
+        This can be used to signify that the board does not have an
+        EEPROM, or that the EEPROM should be hidden from the user.
+
+DM9000_PLATF_SIMPLE_PHY
+
+        Switch to using the simpler PHY polling method which does not
+        try and read the MII PHY state regularly. This is only available
+        when using the internal PHY. See the section on link state polling
+        for more information.
+
+        The config symbol DM9000_FORCE_SIMPLE_PHY_POLL, Kconfig entry
+        "Force simple NSR based PHY polling" allows this flag to be
+        forced on at build time.
+
+
+PHY Link state polling
+----------------------
+
+The driver keeps track of the link state and informs the network core
+about link (carrier) availablilty. This is managed by several methods
+depending on the version of the chip and on which PHY is being used.
+
+For the internal PHY, the original (and currently default) method is
+to read the MII state, either when the status changes if we have the
+necessary interrupt support in the chip or every two seconds via a
+periodic timer.
+
+To reduce the overhead for the internal PHY, there is now the option
+of using the DM9000_FORCE_SIMPLE_PHY_POLL config, or DM9000_PLATF_SIMPLE_PHY
+platform data option to read the summary information without the
+expensive MII accesses. This method is faster, but does not print
+as much information.
+
+When using an external PHY, the driver currently has to poll the MII
+link status as there is no method for getting an interrupt on link change.
+
+
+DM9000A / DM9000B
+-----------------
+
+These chips are functionally similar to the DM9000E and are supported easily
+by the same driver. The features are:
+
+   1) Interrupt on internal PHY state change. This means that the periodic
+      polling of the PHY status may be disabled on these devices when using
+      the internal PHY.
+
+   2) TCP/UDP checksum offloading, which the driver does not currently support.
+
+
+ethtool
+-------
+
+The driver supports the ethtool interface for access to the driver
+state information, the PHY state and the EEPROM.
diff --git a/Documentation/networking/ip-sysctl.txt b/Documentation/networking/ip-sysctl.txt
index 946b66e1b652..d84932650fd3 100644
--- a/Documentation/networking/ip-sysctl.txt
+++ b/Documentation/networking/ip-sysctl.txt
@@ -551,8 +551,9 @@ icmp_echo_ignore_broadcasts - BOOLEAN
 icmp_ratelimit - INTEGER
         Limit the maximal rates for sending ICMP packets whose type matches
         icmp_ratemask (see below) to specific targets.
-        0 to disable any limiting, otherwise the maximal rate in jiffies(1)
-        Default: 100
+        0 to disable any limiting,
+        otherwise the minimal space between responses in milliseconds.
+        Default: 1000
 
 icmp_ratemask - INTEGER
         Mask made of ICMP types for which rates are being limited.
@@ -1023,11 +1024,23 @@ max_addresses - INTEGER
         autoconfigured addresses.
         Default: 16
 
+disable_ipv6 - BOOLEAN
+        Disable IPv6 operation.
+        Default: FALSE (enable IPv6 operation)
+
+accept_dad - INTEGER
+        Whether to accept DAD (Duplicate Address Detection).
+        0: Disable DAD
+        1: Enable DAD (default)
+        2: Enable DAD, and disable IPv6 operation if MAC-based duplicate
+           link-local address has been found.
+
 icmp/*:
 ratelimit - INTEGER
         Limit the maximal rates for sending ICMPv6 packets.
-        0 to disable any limiting, otherwise the maximal rate in jiffies(1)
-        Default: 100
+        0 to disable any limiting,
+        otherwise the minimal space between responses in milliseconds.
+        Default: 1000
 
 
 IPv6 Update by:
diff --git a/Documentation/networking/mac80211_hwsim/README b/Documentation/networking/mac80211_hwsim/README
new file mode 100644
index 000000000000..2ff8ccb8dc37
--- /dev/null
+++ b/Documentation/networking/mac80211_hwsim/README
@@ -0,0 +1,67 @@
+mac80211_hwsim - software simulator of 802.11 radio(s) for mac80211
+Copyright (c) 2008, Jouni Malinen <j@w1.fi>
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License version 2 as
+published by the Free Software Foundation.
+
+
+Introduction
+
+mac80211_hwsim is a Linux kernel module that can be used to simulate
+arbitrary number of IEEE 802.11 radios for mac80211. It can be used to
+test most of the mac80211 functionality and user space tools (e.g.,
+hostapd and wpa_supplicant) in a way that matches very closely with
+the normal case of using real WLAN hardware. From the mac80211 view
+point, mac80211_hwsim is yet another hardware driver, i.e., no changes
+to mac80211 are needed to use this testing tool.
+
+The main goal for mac80211_hwsim is to make it easier for developers
+to test their code and work with new features to mac80211, hostapd,
+and wpa_supplicant. The simulated radios do not have the limitations
+of real hardware, so it is easy to generate an arbitrary test setup
+and always reproduce the same setup for future tests. In addition,
+since all radio operation is simulated, any channel can be used in
+tests regardless of regulatory rules.
+
+mac80211_hwsim kernel module has a parameter 'radios' that can be used
+to select how many radios are simulated (default 2). This allows
+configuration of both very simply setups (e.g., just a single access
+point and a station) or large scale tests (multiple access points with
+hundreds of stations).
+
+mac80211_hwsim works by tracking the current channel of each virtual
+radio and copying all transmitted frames to all other radios that are
+currently enabled and on the same channel as the transmitting
+radio. Software encryption in mac80211 is used so that the frames are
+actually encrypted over the virtual air interface to allow more
+complete testing of encryption.
+
+A global monitoring netdev, hwsim#, is created independent of
+mac80211. This interface can be used to monitor all transmitted frames
+regardless of channel.
+
+
+Simple example
+
+This example shows how to use mac80211_hwsim to simulate two radios:
+one to act as an access point and the other as a station that
+associates with the AP. hostapd and wpa_supplicant are used to take
+care of WPA2-PSK authentication. In addition, hostapd is also
+processing access point side of association.
+
+Please note that the current Linux kernel does not enable AP mode, so a
+simple patch is needed to enable AP mode selection:
+http://johannes.sipsolutions.net/patches/kernel/all/LATEST/006-allow-ap-vlan-modes.patch
+
+
+# Build mac80211_hwsim as part of kernel configuration
+
+# Load the module
+modprobe mac80211_hwsim
+
+# Run hostapd (AP) for wlan0
+hostapd hostapd.conf
+
+# Run wpa_supplicant (station) for wlan1
+wpa_supplicant -Dwext -iwlan1 -c wpa_supplicant.conf
diff --git a/Documentation/networking/mac80211_hwsim/hostapd.conf b/Documentation/networking/mac80211_hwsim/hostapd.conf
new file mode 100644
index 000000000000..08cde7e35f2e
--- /dev/null
+++ b/Documentation/networking/mac80211_hwsim/hostapd.conf
@@ -0,0 +1,11 @@
+interface=wlan0
+driver=nl80211
+
+hw_mode=g
+channel=1
+ssid=mac80211 test
+
+wpa=2
+wpa_key_mgmt=WPA-PSK
+wpa_pairwise=CCMP
+wpa_passphrase=12345678
diff --git a/Documentation/networking/mac80211_hwsim/wpa_supplicant.conf b/Documentation/networking/mac80211_hwsim/wpa_supplicant.conf
new file mode 100644
index 000000000000..299128cff035
--- /dev/null
+++ b/Documentation/networking/mac80211_hwsim/wpa_supplicant.conf
@@ -0,0 +1,10 @@
+ctrl_interface=/var/run/wpa_supplicant
+
+network={
+        ssid="mac80211 test"
+        psk="12345678"
+        key_mgmt=WPA-PSK
+        proto=WPA2
+        pairwise=CCMP
+        group=CCMP
+}
diff --git a/Documentation/networking/multiqueue.txt b/Documentation/networking/multiqueue.txt
index ea5a42e8f79f..e6dc1ee9e8f1 100644
--- a/Documentation/networking/multiqueue.txt
+++ b/Documentation/networking/multiqueue.txt
@@ -3,19 +3,11 @@
                 ===========================================
 
 Section 1: Base driver requirements for implementing multiqueue support
-Section 2: Qdisc support for multiqueue devices
-Section 3: Brief howto using PRIO or RR for multiqueue devices
-
 
 Intro: Kernel support for multiqueue devices
 ---------------------------------------------------------
 
-Kernel support for multiqueue devices is only an API that is presented to the
-netdevice layer for base drivers to implement.  This feature is part of the
-core networking stack, and all network devices will be running on the
-multiqueue-aware stack.  If a base driver only has one queue, then these
-changes are transparent to that driver.
-
+Kernel support for multiqueue devices is always present.
 
 Section 1: Base driver requirements for implementing multiqueue support
 -----------------------------------------------------------------------
@@ -43,73 +35,4 @@ bitmap on device initialization.  Below is an example from e1000:
                 netdev->features |= NETIF_F_MULTI_QUEUE;
 #endif
 
-
-Section 2: Qdisc support for multiqueue devices
------------------------------------------------
-
-Currently two qdiscs support multiqueue devices.  A new round-robin qdisc,
-sch_rr, and sch_prio. The qdisc is responsible for classifying the skb's to
-bands and queues, and will store the queue mapping into skb->queue_mapping.
-Use this field in the base driver to determine which queue to send the skb
-to.
-
-sch_rr has been added for hardware that doesn't want scheduling policies from
-software, so it's a straight round-robin qdisc.  It uses the same syntax and
-classification priomap that sch_prio uses, so it should be intuitive to
-configure for people who've used sch_prio.
-
-In order to utilitize the multiqueue features of the qdiscs, the network
-device layer needs to enable multiple queue support.  This can be done by
-selecting NETDEVICES_MULTIQUEUE under Drivers.
-
-The PRIO qdisc naturally plugs into a multiqueue device.  If
-NETDEVICES_MULTIQUEUE is selected, then on qdisc load, the number of
-bands requested is compared to the number of queues on the hardware.  If they
-are equal, it sets a one-to-one mapping up between the queues and bands.  If
-they're not equal, it will not load the qdisc.  This is the same behavior
-for RR.  Once the association is made, any skb that is classified will have
-skb->queue_mapping set, which will allow the driver to properly queue skb's
-to multiple queues.
-
-
-Section 3: Brief howto using PRIO and RR for multiqueue devices
----------------------------------------------------------------
-
-The userspace command 'tc,' part of the iproute2 package, is used to configure
-qdiscs.  To add the PRIO qdisc to your network device, assuming the device is
-called eth0, run the following command:
-
-# tc qdisc add dev eth0 root handle 1: prio bands 4 multiqueue
-
-This will create 4 bands, 0 being highest priority, and associate those bands
-to the queues on your NIC.  Assuming eth0 has 4 Tx queues, the band mapping
-would look like:
-
-band 0 => queue 0
-band 1 => queue 1
-band 2 => queue 2
-band 3 => queue 3
-
-Traffic will begin flowing through each queue if your TOS values are assigning
-traffic across the various bands.  For example, ssh traffic will always try to
-go out band 0 based on TOS -> Linux priority conversion (realtime traffic),
-so it will be sent out queue 0.  ICMP traffic (pings) fall into the "normal"
-traffic classification, which is band 1.  Therefore pings will be send out
-queue 1 on the NIC.
-
-Note the use of the multiqueue keyword.  This is only in versions of iproute2
-that support multiqueue networking devices; if this is omitted when loading
-a qdisc onto a multiqueue device, the qdisc will load and operate the same
-if it were loaded onto a single-queue device (i.e. - sends all traffic to
-queue 0).
-
-Another alternative to multiqueue band allocation can be done by using the
-multiqueue option and specify 0 bands.  If this is the case, the qdisc will
-allocate the number of bands to equal the number of queues that the device
-reports, and bring the qdisc online.
-
-The behavior of tc filters remains the same, where it will override TOS priority
-classification.
-
-
 Author: Peter P. Waskiewicz Jr. <peter.p.waskiewicz.jr@intel.com>
diff --git a/Documentation/networking/s2io.txt b/Documentation/networking/s2io.txt
index 1e28e2ddb90a..c3d6b4d5d014 100644
--- a/Documentation/networking/s2io.txt
+++ b/Documentation/networking/s2io.txt
@@ -52,13 +52,10 @@ d. MSI/MSI-X. Can be enabled on platforms which support this feature
 (IA64, Xeon) resulting in noticeable performance improvement(upto 7%
 on certain platforms).
 
-e. NAPI. Compile-time option(CONFIG_S2IO_NAPI) for better Rx interrupt 
-moderation.
-
-f. Statistics. Comprehensive MAC-level and software statistics displayed
+e. Statistics. Comprehensive MAC-level and software statistics displayed
 using "ethtool -S" option.
 
-g. Multi-FIFO/Ring. Supports up to 8 transmit queues and receive rings, 
+f. Multi-FIFO/Ring. Supports up to 8 transmit queues and receive rings,
 with multiple steering options.
 
 4.  Command line parameters
diff --git a/Documentation/powerpc/booting-without-of.txt b/Documentation/powerpc/booting-without-of.txt
index 1d2a772506cf..46a9dba11f2f 100644
--- a/Documentation/powerpc/booting-without-of.txt
+++ b/Documentation/powerpc/booting-without-of.txt
@@ -58,6 +58,7 @@ Table of Contents
       o) Xilinx IP cores
       p) Freescale Synchronous Serial Interface
           q) USB EHCI controllers
+      r) MDIO on GPIOs
 
   VII - Marvell Discovery mv64[345]6x System Controller chips
     1) The /system-controller node
@@ -2870,6 +2871,26 @@ platforms are moved over to use the flattened-device-tree model.
                 reg = <0xe8000000 32>;
         };
 
+   r) MDIO on GPIOs
+
+   Currently defined compatibles:
+   - virtual,gpio-mdio
+
+   MDC and MDIO lines connected to GPIO controllers are listed in the
+   gpios property as described in section VIII.1 in the following order:
+
+   MDC, MDIO.
+
+   Example:
+
+        mdio {
+                compatible = "virtual,mdio-gpio";
+                #address-cells = <1>;
+                #size-cells = <0>;
+                gpios = <&qe_pio_a 11
+                         &qe_pio_c 6>;
+        };
+
 VII - Marvell Discovery mv64[345]6x System Controller chips
 ===========================================================
 
diff --git a/Documentation/rfkill.txt b/Documentation/rfkill.txt
index a83ff23cd68c..0843ed0163a5 100644
--- a/Documentation/rfkill.txt
+++ b/Documentation/rfkill.txt
@@ -1,89 +1,528 @@
 rfkill - RF switch subsystem support
 ====================================
 
-1 Implementation details
-2 Driver support
-3 Userspace support
+1 Introduction
+2 Implementation details
+3 Kernel driver guidelines
+3.1 wireless device drivers
+3.2 platform/switch drivers
+3.3 input device drivers
+4 Kernel API
+5 Userspace support
 
-===============================================================================
-1: Implementation details
 
-The rfkill switch subsystem offers support for keys often found on laptops
-to enable wireless devices like WiFi and Bluetooth.
+1. Introduction:
+
+The rfkill switch subsystem exists to add a generic interface to circuitry that
+can enable or disable the signal output of a wireless *transmitter* of any
+type.  By far, the most common use is to disable radio-frequency transmitters.
 
-This is done by providing the user 3 possibilities:
- 1 - The rfkill system handles all events; userspace is not aware of events.
- 2 - The rfkill system handles all events; userspace is informed about the events.
- 3 - The rfkill system does not handle events; userspace handles all events.
+Note that disabling the signal output means that the the transmitter is to be
+made to not emit any energy when "blocked".  rfkill is not about blocking data
+transmissions, it is about blocking energy emission.
 
-The buttons to enable and disable the wireless radios are important in
+The rfkill subsystem offers support for keys and switches often found on
+laptops to enable wireless devices like WiFi and Bluetooth, so that these keys
+and switches actually perform an action in all wireless devices of a given type
+attached to the system.
+
+The buttons to enable and disable the wireless transmitters are important in
 situations where the user is for example using his laptop on a location where
-wireless radios _must_ be disabled (e.g. airplanes).
-Because of this requirement, userspace support for the keys should not be
-made mandatory. Because userspace might want to perform some additional smarter
-tasks when the key is pressed, rfkill still provides userspace the possibility
-to take over the task to handle the key events.
+radio-frequency transmitters _must_ be disabled (e.g. airplanes).
+
+Because of this requirement, userspace support for the keys should not be made
+mandatory.  Because userspace might want to perform some additional smarter
+tasks when the key is pressed, rfkill provides userspace the possibility to
+take over the task to handle the key events.
+
+===============================================================================
+2: Implementation details
+
+The rfkill subsystem is composed of various components: the rfkill class, the
+rfkill-input module (an input layer handler), and some specific input layer
+events.
+
+The rfkill class provides kernel drivers with an interface that allows them to
+know when they should enable or disable a wireless network device transmitter.
+This is enabled by the CONFIG_RFKILL Kconfig option.
+
+The rfkill class support makes sure userspace will be notified of all state
+changes on rfkill devices through uevents.  It provides a notification chain
+for interested parties in the kernel to also get notified of rfkill state
+changes in other drivers.  It creates several sysfs entries which can be used
+by userspace.  See section "Userspace support".
+
+The rfkill-input module provides the kernel with the ability to implement a
+basic response when the user presses a key or button (or toggles a switch)
+related to rfkill functionality.  It is an in-kernel implementation of default
+policy of reacting to rfkill-related input events and neither mandatory nor
+required for wireless drivers to operate.  It is enabled by the
+CONFIG_RFKILL_INPUT Kconfig option.
+
+rfkill-input is a rfkill-related events input layer handler.  This handler will
+listen to all rfkill key events and will change the rfkill state of the
+wireless devices accordingly.  With this option enabled userspace could either
+do nothing or simply perform monitoring tasks.
+
+The rfkill-input module also provides EPO (emergency power-off) functionality
+for all wireless transmitters.  This function cannot be overridden, and it is
+always active.  rfkill EPO is related to *_RFKILL_ALL input layer events.
+
+
+Important terms for the rfkill subsystem:
+
+In order to avoid confusion, we avoid the term "switch" in rfkill when it is
+referring to an electronic control circuit that enables or disables a
+transmitter.  We reserve it for the physical device a human manipulates
+(which is an input device, by the way):
+
+rfkill switch:
+
+        A physical device a human manipulates.  Its state can be perceived by
+        the kernel either directly (through a GPIO pin, ACPI GPE) or by its
+        effect on a rfkill line of a wireless device.
+
+rfkill controller:
+
+        A hardware circuit that controls the state of a rfkill line, which a
+        kernel driver can interact with *to modify* that state (i.e. it has
+        either write-only or read/write access).
+
+rfkill line:
+
+        An input channel (hardware or software) of a wireless device, which
+        causes a wireless transmitter to stop emitting energy (BLOCK) when it
+        is active.  Point of view is extremely important here: rfkill lines are
+        always seen from the PoV of a wireless device (and its driver).
+
+soft rfkill line/software rfkill line:
+
+        A rfkill line the wireless device driver can directly change the state
+        of.  Related to rfkill_state RFKILL_STATE_SOFT_BLOCKED.
+
+hard rfkill line/hardware rfkill line:
+
+        A rfkill line that works fully in hardware or firmware, and that cannot
+        be overridden by the kernel driver.  The hardware device or the
+        firmware just exports its status to the driver, but it is read-only.
+        Related to rfkill_state RFKILL_STATE_HARD_BLOCKED.
+
+The enum rfkill_state describes the rfkill state of a transmitter:
+
+When a rfkill line or rfkill controller is in the RFKILL_STATE_UNBLOCKED state,
+the wireless transmitter (radio TX circuit for example) is *enabled*.  When the
+it is in the RFKILL_STATE_SOFT_BLOCKED or RFKILL_STATE_HARD_BLOCKED, the
+wireless transmitter is to be *blocked* from operating.
+
+RFKILL_STATE_SOFT_BLOCKED indicates that a call to toggle_radio() can change
+that state.  RFKILL_STATE_HARD_BLOCKED indicates that a call to toggle_radio()
+will not be able to change the state and will return with a suitable error if
+attempts are made to set the state to RFKILL_STATE_UNBLOCKED.
+
+RFKILL_STATE_HARD_BLOCKED is used by drivers to signal that the device is
+locked in the BLOCKED state by a hardwire rfkill line (typically an input pin
+that, when active, forces the transmitter to be disabled) which the driver
+CANNOT override.
+
+Full rfkill functionality requires two different subsystems to cooperate: the
+input layer and the rfkill class.  The input layer issues *commands* to the
+entire system requesting that devices registered to the rfkill class change
+state.  The way this interaction happens is not complex, but it is not obvious
+either:
+
+Kernel Input layer:
+
+        * Generates KEY_WWAN, KEY_WLAN, KEY_BLUETOOTH, SW_RFKILL_ALL, and
+          other such events when the user presses certain keys, buttons, or
+          toggles certain physical switches.
+
+        THE INPUT LAYER IS NEVER USED TO PROPAGATE STATUS, NOTIFICATIONS OR THE
+        KIND OF STUFF AN ON-SCREEN-DISPLAY APPLICATION WOULD REPORT.  It is
+        used to issue *commands* for the system to change behaviour, and these
+        commands may or may not be carried out by some kernel driver or
+        userspace application.  It follows that doing user feedback based only
+        on input events is broken, as there is no guarantee that an input event
+        will be acted upon.
+
+        Most wireless communication device drivers implementing rfkill
+        functionality MUST NOT generate these events, and have no reason to
+        register themselves with the input layer.  Doing otherwise is a common
+        misconception.  There is an API to propagate rfkill status change
+        information, and it is NOT the input layer.
+
+rfkill class:
+
+        * Calls a hook in a driver to effectively change the wireless
+          transmitter state;
+        * Keeps track of the wireless transmitter state (with help from
+          the driver);
+        * Generates userspace notifications (uevents) and a call to a
+          notification chain (kernel) when there is a wireless transmitter
+          state change;
+        * Connects a wireless communications driver with the common rfkill
+          control system, which, for example, allows actions such as
+          "switch all bluetooth devices offline" to be carried out by
+          userspace or by rfkill-input.
+
+        THE RFKILL CLASS NEVER ISSUES INPUT EVENTS.  THE RFKILL CLASS DOES
+        NOT LISTEN TO INPUT EVENTS.  NO DRIVER USING THE RFKILL CLASS SHALL
+        EVER LISTEN TO, OR ACT ON RFKILL INPUT EVENTS.  Doing otherwise is
+        a layering violation.
+
+        Most wireless data communication drivers in the kernel have just to
+        implement the rfkill class API to work properly.  Interfacing to the
+        input layer is not often required (and is very often a *bug*) on
+        wireless drivers.
+
+        Platform drivers often have to attach to the input layer to *issue*
+        (but never to listen to) rfkill events for rfkill switches, and also to
+        the rfkill class to export a control interface for the platform rfkill
+        controllers to the rfkill subsystem.  This does NOT mean the rfkill
+        switch is attached to a rfkill class (doing so is almost always wrong).
+        It just means the same kernel module is the driver for different
+        devices (rfkill switches and rfkill controllers).
+
+
+Userspace input handlers (uevents) or kernel input handlers (rfkill-input):
+
+        * Implements the policy of what should happen when one of the input
+          layer events related to rfkill operation is received.
+        * Uses the sysfs interface (userspace) or private rfkill API calls
+          to tell the devices registered with the rfkill class to change
+          their state (i.e. translates the input layer event into real
+          action).
+        * rfkill-input implements EPO by handling EV_SW SW_RFKILL_ALL 0
+          (power off all transmitters) in a special way: it ignores any
+          overrides and local state cache and forces all transmitters to the
+          RFKILL_STATE_SOFT_BLOCKED state (including those which are already
+          supposed to be BLOCKED).  Note that the opposite event (power on all
+          transmitters) is handled normally.
+
+Userspace uevent handler or kernel platform-specific drivers hooked to the
+rfkill notifier chain:
+
+        * Taps into the rfkill notifier chain or to KOBJ_CHANGE uevents,
+          in order to know when a device that is registered with the rfkill
+          class changes state;
+        * Issues feedback notifications to the user;
+        * In the rare platforms where this is required, synthesizes an input
+          event to command all *OTHER* rfkill devices to also change their
+          statues when a specific rfkill device changes state.
+
+
+===============================================================================
+3: Kernel driver guidelines
+
+Remember: point-of-view is everything for a driver that connects to the rfkill
+subsystem.  All the details below must be measured/perceived from the point of
+view of the specific driver being modified.
+
+The first thing one needs to know is whether his driver should be talking to
+the rfkill class or to the input layer.  In rare cases (platform drivers), it
+could happen that you need to do both, as platform drivers often handle a
+variety of devices in the same driver.
+
+Do not mistake input devices for rfkill controllers.  The only type of "rfkill
+switch" device that is to be registered with the rfkill class are those
+directly controlling the circuits that cause a wireless transmitter to stop
+working (or the software equivalent of them), i.e. what we call a rfkill
+controller.  Every other kind of "rfkill switch" is just an input device and
+MUST NOT be registered with the rfkill class.
+
+A driver should register a device with the rfkill class when ALL of the
+following conditions are met (they define a rfkill controller):
+
+1. The device is/controls a data communications wireless transmitter;
+
+2. The kernel can interact with the hardware/firmware to CHANGE the wireless
+   transmitter state (block/unblock TX operation);
+
+3. The transmitter can be made to not emit any energy when "blocked":
+   rfkill is not about blocking data transmissions, it is about blocking
+   energy emission;
+
+A driver should register a device with the input subsystem to issue
+rfkill-related events (KEY_WLAN, KEY_BLUETOOTH, KEY_WWAN, KEY_WIMAX,
+SW_RFKILL_ALL, etc) when ALL of the folowing conditions are met:
+
+1. It is directly related to some physical device the user interacts with, to
+   command the O.S./firmware/hardware to enable/disable a data communications
+   wireless transmitter.
+
+   Examples of the physical device are: buttons, keys and switches the user
+   will press/touch/slide/switch to enable or disable the wireless
+   communication device.
+
+2. It is NOT slaved to another device, i.e. there is no other device that
+   issues rfkill-related input events in preference to this one.
 
-The system inside the kernel has been split into 2 separate sections:
-        1 - RFKILL
-        2 - RFKILL_INPUT
+   Please refer to the corner cases and examples section for more details.
 
-The first option enables rfkill support and will make sure userspace will
-be notified of any events through the input device. It also creates several
-sysfs entries which can be used by userspace. See section "Userspace support".
+When in doubt, do not issue input events.  For drivers that should generate
+input events in some platforms, but not in others (e.g. b43), the best solution
+is to NEVER generate input events in the first place.  That work should be
+deferred to a platform-specific kernel module (which will know when to generate
+events through the rfkill notifier chain) or to userspace.  This avoids the
+usual maintenance problems with DMI whitelisting.
 
-The second option provides an rfkill input handler. This handler will
-listen to all rfkill key events and will toggle the radio accordingly.
-With this option enabled userspace could either do nothing or simply
-perform monitoring tasks.
 
+Corner cases and examples:
 ====================================
-2: Driver support
 
-To build a driver with rfkill subsystem support, the driver should
-depend on the Kconfig symbol RFKILL; it should _not_ depend on
-RKFILL_INPUT.
+1. If the device is an input device that, because of hardware or firmware,
+causes wireless transmitters to be blocked regardless of the kernel's will, it
+is still just an input device, and NOT to be registered with the rfkill class.
 
-Unless key events trigger an interrupt to which the driver listens, polling
-will be required to determine the key state changes. For this the input
-layer providers the input-polldev handler.
+2. If the wireless transmitter switch control is read-only, it is an input
+device and not to be registered with the rfkill class (and maybe not to be made
+an input layer event source either, see below).
 
-A driver should implement a few steps to correctly make use of the
-rfkill subsystem. First for non-polling drivers:
+3. If there is some other device driver *closer* to the actual hardware the
+user interacted with (the button/switch/key) to issue an input event, THAT is
+the device driver that should be issuing input events.
 
-        - rfkill_allocate()
-        - input_allocate_device()
-        - rfkill_register()
-        - input_register_device()
+E.g:
+  [RFKILL slider switch] -- [GPIO hardware] -- [WLAN card rf-kill input]
+                           (platform driver)    (wireless card driver)
+
+The user is closer to the RFKILL slide switch plaform driver, so the driver
+which must issue input events is the platform driver looking at the GPIO
+hardware, and NEVER the wireless card driver (which is just a slave).  It is
+very likely that there are other leaves than just the WLAN card rf-kill input
+(e.g. a bluetooth card, etc)...
+
+On the other hand, some embedded devices do this:
+
+  [RFKILL slider switch] -- [WLAN card rf-kill input]
+                             (wireless card driver)
+
+In this situation, the wireless card driver *could* register itself as an input
+device and issue rf-kill related input events... but in order to AVOID the need
+for DMI whitelisting, the wireless card driver does NOT do it.  Userspace (HAL)
+or a platform driver (that exists only on these embedded devices) will do the
+dirty job of issuing the input events.
+
+
+COMMON MISTAKES in kernel drivers, related to rfkill:
+====================================
+
+1. NEVER confuse input device keys and buttons with input device switches.
+
+  1a. Switches are always set or reset.  They report the current state
+      (on position or off position).
+
+  1b. Keys and buttons are either in the pressed or not-pressed state, and
+      that's it.  A "button" that latches down when you press it, and
+      unlatches when you press it again is in fact a switch as far as input
+      devices go.
+
+Add the SW_* events you need for switches, do NOT try to emulate a button using
+KEY_* events just because there is no such SW_* event yet.  Do NOT try to use,
+for example, KEY_BLUETOOTH when you should be using SW_BLUETOOTH instead.
+
+2. Input device switches (sources of EV_SW events) DO store their current state
+(so you *must* initialize it by issuing a gratuitous input layer event on
+driver start-up and also when resuming from sleep), and that state CAN be
+queried from userspace through IOCTLs.  There is no sysfs interface for this,
+but that doesn't mean you should break things trying to hook it to the rfkill
+class to get a sysfs interface :-)
+
+3. Do not issue *_RFKILL_ALL events by default, unless you are sure it is the
+correct event for your switch/button.  These events are emergency power-off
+events when they are trying to turn the transmitters off.  An example of an
+input device which SHOULD generate *_RFKILL_ALL events is the wireless-kill
+switch in a laptop which is NOT a hotkey, but a real switch that kills radios
+in hardware, even if the O.S. has gone to lunch.  An example of an input device
+which SHOULD NOT generate *_RFKILL_ALL events by default, is any sort of hot
+key that does nothing by itself, as well as any hot key that is type-specific
+(e.g. the one for WLAN).
+
+
+3.1 Guidelines for wireless device drivers
+------------------------------------------
+
+1. Each independent transmitter in a wireless device (usually there is only one
+transmitter per device) should have a SINGLE rfkill class attached to it.
+
+2. If the device does not have any sort of hardware assistance to allow the
+driver to rfkill the device, the driver should emulate it by taking all actions
+required to silence the transmitter.
+
+3. If it is impossible to silence the transmitter (i.e. it still emits energy,
+even if it is just in brief pulses, when there is no data to transmit and there
+is no hardware support to turn it off) do NOT lie to the users.  Do not attach
+it to a rfkill class.  The rfkill subsystem does not deal with data
+transmission, it deals with energy emission.  If the transmitter is emitting
+energy, it is not blocked in rfkill terms.
+
+4. It doesn't matter if the device has multiple rfkill input lines affecting
+the same transmitter, their combined state is to be exported as a single state
+per transmitter (see rule 1).
+
+This rule exists because users of the rfkill subsystem expect to get (and set,
+when possible) the overall transmitter rfkill state, not of a particular rfkill
+line.
+
+Example of a WLAN wireless driver connected to the rfkill subsystem:
+--------------------------------------------------------------------
+
+A certain WLAN card has one input pin that causes it to block the transmitter
+and makes the status of that input pin available (only for reading!) to the
+kernel driver.  This is a hard rfkill input line (it cannot be overridden by
+the kernel driver).
+
+The card also has one PCI register that, if manipulated by the driver, causes
+it to block the transmitter.  This is a soft rfkill input line.
+
+It has also a thermal protection circuitry that shuts down its transmitter if
+the card overheats, and makes the status of that protection available (only for
+reading!) to the kernel driver.  This is also a hard rfkill input line.
+
+If either one of these rfkill lines are active, the transmitter is blocked by
+the hardware and forced offline.
+
+The driver should allocate and attach to its struct device *ONE* instance of
+the rfkill class (there is only one transmitter).
+
+It can implement the get_state() hook, and return RFKILL_STATE_HARD_BLOCKED if
+either one of its two hard rfkill input lines are active.  If the two hard
+rfkill lines are inactive, it must return RFKILL_STATE_SOFT_BLOCKED if its soft
+rfkill input line is active.  Only if none of the rfkill input lines are
+active, will it return RFKILL_STATE_UNBLOCKED.
 
-For polling drivers:
+If it doesn't implement the get_state() hook, it must make sure that its calls
+to rfkill_force_state() are enough to keep the status always up-to-date, and it
+must do a rfkill_force_state() on resume from sleep.
 
+Every time the driver gets a notification from the card that one of its rfkill
+lines changed state (polling might be needed on badly designed cards that don't
+generate interrupts for such events), it recomputes the rfkill state as per
+above, and calls rfkill_force_state() to update it.
+
+The driver should implement the toggle_radio() hook, that:
+
+1. Returns an error if one of the hardware rfkill lines are active, and the
+caller asked for RFKILL_STATE_UNBLOCKED.
+
+2. Activates the soft rfkill line if the caller asked for state
+RFKILL_STATE_SOFT_BLOCKED.  It should do this even if one of the hard rfkill
+lines are active, effectively double-blocking the transmitter.
+
+3. Deactivates the soft rfkill line if none of the hardware rfkill lines are
+active and the caller asked for RFKILL_STATE_UNBLOCKED.
+
+===============================================================================
+4: Kernel API
+
+To build a driver with rfkill subsystem support, the driver should depend on
+(or select) the Kconfig symbol RFKILL; it should _not_ depend on RKFILL_INPUT.
+
+The hardware the driver talks to may be write-only (where the current state
+of the hardware is unknown), or read-write (where the hardware can be queried
+about its current state).
+
+The rfkill class will call the get_state hook of a device every time it needs
+to know the *real* current state of the hardware.  This can happen often.
+
+Some hardware provides events when its status changes.  In these cases, it is
+best for the driver to not provide a get_state hook, and instead register the
+rfkill class *already* with the correct status, and keep it updated using
+rfkill_force_state() when it gets an event from the hardware.
+
+There is no provision for a statically-allocated rfkill struct.  You must
+use rfkill_allocate() to allocate one.
+
+You should:
         - rfkill_allocate()
-        - input_allocate_polled_device()
+        - modify rfkill fields (flags, name)
+        - modify state to the current hardware state (THIS IS THE ONLY TIME
+          YOU CAN ACCESS state DIRECTLY)
         - rfkill_register()
-        - input_register_polled_device()
 
-When a key event has been detected, the correct event should be
-sent over the input device which has been registered by the driver.
+The only way to set a device to the RFKILL_STATE_HARD_BLOCKED state is through
+a suitable return of get_state() or through rfkill_force_state().
 
-====================================
-3: Userspace support
+When a device is in the RFKILL_STATE_HARD_BLOCKED state, the only way to switch
+it to a different state is through a suitable return of get_state() or through
+rfkill_force_state().
+
+If toggle_radio() is called to set a device to state RFKILL_STATE_SOFT_BLOCKED
+when that device is already at the RFKILL_STATE_HARD_BLOCKED state, it should
+not return an error.  Instead, it should try to double-block the transmitter,
+so that its state will change from RFKILL_STATE_HARD_BLOCKED to
+RFKILL_STATE_SOFT_BLOCKED should the hardware blocking cease.
 
-For each key an input device will be created which will send out the correct
-key event when the rfkill key has been pressed.
+Please refer to the source for more documentation.
+
+===============================================================================
+5: Userspace support
+
+rfkill devices issue uevents (with an action of "change"), with the following
+environment variables set:
+
+RFKILL_NAME
+RFKILL_STATE
+RFKILL_TYPE
+
+The ABI for these variables is defined by the sysfs attributes.  It is best
+to take a quick look at the source to make sure of the possible values.
+
+It is expected that HAL will trap those, and bridge them to DBUS, etc.  These
+events CAN and SHOULD be used to give feedback to the user about the rfkill
+status of the system.
+
+Input devices may issue events that are related to rfkill.  These are the
+various KEY_* events and SW_* events supported by rfkill-input.c.
+
+******IMPORTANT******
+When rfkill-input is ACTIVE, userspace is NOT TO CHANGE THE STATE OF AN RFKILL
+SWITCH IN RESPONSE TO AN INPUT EVENT also handled by rfkill-input, unless it
+has set to true the user_claim attribute for that particular switch.  This rule
+is *absolute*; do NOT violate it.
+******IMPORTANT******
+
+Userspace must not assume it is the only source of control for rfkill switches.
+Their state CAN and WILL change due to firmware actions, direct user actions,
+and the rfkill-input EPO override for *_RFKILL_ALL.
+
+When rfkill-input is not active, userspace must initiate a rfkill status
+change by writing to the "state" attribute in order for anything to happen.
+
+Take particular care to implement EV_SW SW_RFKILL_ALL properly.  When that
+switch is set to OFF, *every* rfkill device *MUST* be immediately put into the
+RFKILL_STATE_SOFT_BLOCKED state, no questions asked.
 
 The following sysfs entries will be created:
 
         name: Name assigned by driver to this key (interface or driver name).
         type: Name of the key type ("wlan", "bluetooth", etc).
-        state: Current state of the key. 1: On, 0: Off.
+        state: Current state of the transmitter
+                0: RFKILL_STATE_SOFT_BLOCKED
+                        transmitter is forced off, but one can override it
+                        by a write to the state attribute;
+                1: RFKILL_STATE_UNBLOCKED
+                        transmiter is NOT forced off, and may operate if
+                        all other conditions for such operation are met
+                        (such as interface is up and configured, etc);
+                2: RFKILL_STATE_HARD_BLOCKED
+                        transmitter is forced off by something outside of
+                        the driver's control.  One cannot set a device to
+                        this state through writes to the state attribute;
         claim: 1: Userspace handles events, 0: Kernel handles events
 
 Both the "state" and "claim" entries are also writable. For the "state" entry
-this means that when 1 or 0 is written all radios, not yet in the requested
-state, will be will be toggled accordingly.
+this means that when 1 or 0 is written, the device rfkill state (if not yet in
+the requested state), will be will be toggled accordingly.
+
 For the "claim" entry writing 1 to it means that the kernel no longer handles
 key events even though RFKILL_INPUT input was enabled. When "claim" has been
 set to 0, userspace should make sure that it listens for the input events or
-check the sysfs "state" entry regularly to correctly perform the required
-tasks when the rkfill key is pressed.
+check the sysfs "state" entry regularly to correctly perform the required tasks
+when the rkfill key is pressed.
+
+A note about input devices and EV_SW events:
+
+In order to know the current state of an input device switch (like
+SW_RFKILL_ALL), you will need to use an IOCTL.  That information is not
+available through sysfs in a generic way at this time, and it is not available
+through the rfkill class AT ALL.