diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/feature-removal-schedule.txt | 12 | ||||
| -rw-r--r-- | Documentation/networking/bonding.txt | 110 | ||||
| -rw-r--r-- | Documentation/networking/dm9000.txt | 167 | ||||
| -rw-r--r-- | Documentation/networking/ip-sysctl.txt | 21 | ||||
| -rw-r--r-- | Documentation/networking/mac80211_hwsim/README | 67 | ||||
| -rw-r--r-- | Documentation/networking/mac80211_hwsim/hostapd.conf | 11 | ||||
| -rw-r--r-- | Documentation/networking/mac80211_hwsim/wpa_supplicant.conf | 10 | ||||
| -rw-r--r-- | Documentation/networking/multiqueue.txt | 79 | ||||
| -rw-r--r-- | Documentation/networking/s2io.txt | 7 | ||||
| -rw-r--r-- | Documentation/powerpc/booting-without-of.txt | 21 | ||||
| -rw-r--r-- | Documentation/rfkill.txt | 547 |
11 files changed, 881 insertions, 171 deletions
diff --git a/Documentation/feature-removal-schedule.txt b/Documentation/feature-removal-schedule.txt index 46ece3fba6f..8319c462c9f 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 a0cda062bc3..7fa7fe71d7a 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 00000000000..65df3dea556 --- /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 946b66e1b65..d84932650fd 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 00000000000..2ff8ccb8dc3 --- /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 00000000000..08cde7e35f2 --- /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 00000000000..299128cff03 --- /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 ea5a42e8f79..e6dc1ee9e8f 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 1e28e2ddb90..c3d6b4d5d01 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 1d2a772506c..46a9dba11f2 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 a83ff23cd68..0843ed0163a 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. |