Ivo van Doorn | dac24ab | 2007-09-13 09:22:55 +0200 | [diff] [blame] | 1 | rfkill - RF switch subsystem support |
| 2 | ==================================== |
| 3 | |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 4 | 1 Introduction |
| 5 | 2 Implementation details |
| 6 | 3 Kernel driver guidelines |
Henrique de Moraes Holschuh | f7983f7 | 2008-06-23 17:46:43 -0300 | [diff] [blame] | 7 | 3.1 wireless device drivers |
| 8 | 3.2 platform/switch drivers |
| 9 | 3.3 input device drivers |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 10 | 4 Kernel API |
| 11 | 5 Userspace support |
Ivo van Doorn | dac24ab | 2007-09-13 09:22:55 +0200 | [diff] [blame] | 12 | |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 13 | |
| 14 | 1. Introduction: |
Ivo van Doorn | dac24ab | 2007-09-13 09:22:55 +0200 | [diff] [blame] | 15 | |
Henrique de Moraes Holschuh | f3146af | 2008-06-23 17:22:56 -0300 | [diff] [blame] | 16 | The rfkill switch subsystem exists to add a generic interface to circuitry that |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 17 | can enable or disable the signal output of a wireless *transmitter* of any |
| 18 | type. By far, the most common use is to disable radio-frequency transmitters. |
Henrique de Moraes Holschuh | f3146af | 2008-06-23 17:22:56 -0300 | [diff] [blame] | 19 | |
Henrique de Moraes Holschuh | f7983f7 | 2008-06-23 17:46:43 -0300 | [diff] [blame] | 20 | Note that disabling the signal output means that the the transmitter is to be |
| 21 | made to not emit any energy when "blocked". rfkill is not about blocking data |
| 22 | transmissions, it is about blocking energy emission. |
| 23 | |
| 24 | The rfkill subsystem offers support for keys and switches often found on |
| 25 | laptops to enable wireless devices like WiFi and Bluetooth, so that these keys |
| 26 | and switches actually perform an action in all wireless devices of a given type |
| 27 | attached to the system. |
Henrique de Moraes Holschuh | f3146af | 2008-06-23 17:22:56 -0300 | [diff] [blame] | 28 | |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 29 | The buttons to enable and disable the wireless transmitters are important in |
Ivo van Doorn | dac24ab | 2007-09-13 09:22:55 +0200 | [diff] [blame] | 30 | situations where the user is for example using his laptop on a location where |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 31 | radio-frequency transmitters _must_ be disabled (e.g. airplanes). |
| 32 | |
| 33 | Because of this requirement, userspace support for the keys should not be made |
| 34 | mandatory. Because userspace might want to perform some additional smarter |
| 35 | tasks when the key is pressed, rfkill provides userspace the possibility to |
| 36 | take over the task to handle the key events. |
| 37 | |
| 38 | =============================================================================== |
| 39 | 2: Implementation details |
| 40 | |
Henrique de Moraes Holschuh | f7983f7 | 2008-06-23 17:46:43 -0300 | [diff] [blame] | 41 | The rfkill subsystem is composed of various components: the rfkill class, the |
| 42 | rfkill-input module (an input layer handler), and some specific input layer |
| 43 | events. |
| 44 | |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 45 | The rfkill class provides kernel drivers with an interface that allows them to |
| 46 | know when they should enable or disable a wireless network device transmitter. |
Henrique de Moraes Holschuh | f7983f7 | 2008-06-23 17:46:43 -0300 | [diff] [blame] | 47 | This is enabled by the CONFIG_RFKILL Kconfig option. |
| 48 | |
| 49 | The rfkill class support makes sure userspace will be notified of all state |
| 50 | changes on rfkill devices through uevents. It provides a notification chain |
| 51 | for interested parties in the kernel to also get notified of rfkill state |
| 52 | changes in other drivers. It creates several sysfs entries which can be used |
| 53 | by userspace. See section "Userspace support". |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 54 | |
| 55 | The rfkill-input module provides the kernel with the ability to implement a |
| 56 | basic response when the user presses a key or button (or toggles a switch) |
| 57 | related to rfkill functionality. It is an in-kernel implementation of default |
| 58 | policy of reacting to rfkill-related input events and neither mandatory nor |
Henrique de Moraes Holschuh | f7983f7 | 2008-06-23 17:46:43 -0300 | [diff] [blame] | 59 | required for wireless drivers to operate. It is enabled by the |
| 60 | CONFIG_RFKILL_INPUT Kconfig option. |
| 61 | |
| 62 | rfkill-input is a rfkill-related events input layer handler. This handler will |
| 63 | listen to all rfkill key events and will change the rfkill state of the |
| 64 | wireless devices accordingly. With this option enabled userspace could either |
| 65 | do nothing or simply perform monitoring tasks. |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 66 | |
| 67 | The rfkill-input module also provides EPO (emergency power-off) functionality |
Henrique de Moraes Holschuh | f7983f7 | 2008-06-23 17:46:43 -0300 | [diff] [blame] | 68 | for all wireless transmitters. This function cannot be overridden, and it is |
| 69 | always active. rfkill EPO is related to *_RFKILL_ALL input layer events. |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 70 | |
Ivo van Doorn | dac24ab | 2007-09-13 09:22:55 +0200 | [diff] [blame] | 71 | |
Henrique de Moraes Holschuh | f7983f7 | 2008-06-23 17:46:43 -0300 | [diff] [blame] | 72 | Important terms for the rfkill subsystem: |
Ivo van Doorn | dac24ab | 2007-09-13 09:22:55 +0200 | [diff] [blame] | 73 | |
Henrique de Moraes Holschuh | f7983f7 | 2008-06-23 17:46:43 -0300 | [diff] [blame] | 74 | In order to avoid confusion, we avoid the term "switch" in rfkill when it is |
| 75 | referring to an electronic control circuit that enables or disables a |
| 76 | transmitter. We reserve it for the physical device a human manipulates |
| 77 | (which is an input device, by the way): |
Ivo van Doorn | dac24ab | 2007-09-13 09:22:55 +0200 | [diff] [blame] | 78 | |
Henrique de Moraes Holschuh | f7983f7 | 2008-06-23 17:46:43 -0300 | [diff] [blame] | 79 | rfkill switch: |
Ivo van Doorn | dac24ab | 2007-09-13 09:22:55 +0200 | [diff] [blame] | 80 | |
Henrique de Moraes Holschuh | f7983f7 | 2008-06-23 17:46:43 -0300 | [diff] [blame] | 81 | A physical device a human manipulates. Its state can be perceived by |
| 82 | the kernel either directly (through a GPIO pin, ACPI GPE) or by its |
| 83 | effect on a rfkill line of a wireless device. |
| 84 | |
| 85 | rfkill controller: |
| 86 | |
| 87 | A hardware circuit that controls the state of a rfkill line, which a |
| 88 | kernel driver can interact with *to modify* that state (i.e. it has |
| 89 | either write-only or read/write access). |
| 90 | |
| 91 | rfkill line: |
| 92 | |
| 93 | An input channel (hardware or software) of a wireless device, which |
| 94 | causes a wireless transmitter to stop emitting energy (BLOCK) when it |
| 95 | is active. Point of view is extremely important here: rfkill lines are |
| 96 | always seen from the PoV of a wireless device (and its driver). |
| 97 | |
| 98 | soft rfkill line/software rfkill line: |
| 99 | |
| 100 | A rfkill line the wireless device driver can directly change the state |
| 101 | of. Related to rfkill_state RFKILL_STATE_SOFT_BLOCKED. |
| 102 | |
| 103 | hard rfkill line/hardware rfkill line: |
| 104 | |
| 105 | A rfkill line that works fully in hardware or firmware, and that cannot |
| 106 | be overridden by the kernel driver. The hardware device or the |
| 107 | firmware just exports its status to the driver, but it is read-only. |
| 108 | Related to rfkill_state RFKILL_STATE_HARD_BLOCKED. |
| 109 | |
| 110 | The enum rfkill_state describes the rfkill state of a transmitter: |
| 111 | |
| 112 | When a rfkill line or rfkill controller is in the RFKILL_STATE_UNBLOCKED state, |
| 113 | the wireless transmitter (radio TX circuit for example) is *enabled*. When the |
| 114 | it is in the RFKILL_STATE_SOFT_BLOCKED or RFKILL_STATE_HARD_BLOCKED, the |
| 115 | wireless transmitter is to be *blocked* from operating. |
Henrique de Moraes Holschuh | 5005657 | 2008-06-23 17:46:42 -0300 | [diff] [blame] | 116 | |
| 117 | RFKILL_STATE_SOFT_BLOCKED indicates that a call to toggle_radio() can change |
| 118 | that state. RFKILL_STATE_HARD_BLOCKED indicates that a call to toggle_radio() |
| 119 | will not be able to change the state and will return with a suitable error if |
| 120 | attempts are made to set the state to RFKILL_STATE_UNBLOCKED. |
| 121 | |
| 122 | RFKILL_STATE_HARD_BLOCKED is used by drivers to signal that the device is |
| 123 | locked in the BLOCKED state by a hardwire rfkill line (typically an input pin |
| 124 | that, when active, forces the transmitter to be disabled) which the driver |
| 125 | CANNOT override. |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 126 | |
| 127 | Full rfkill functionality requires two different subsystems to cooperate: the |
| 128 | input layer and the rfkill class. The input layer issues *commands* to the |
| 129 | entire system requesting that devices registered to the rfkill class change |
| 130 | state. The way this interaction happens is not complex, but it is not obvious |
| 131 | either: |
| 132 | |
| 133 | Kernel Input layer: |
| 134 | |
| 135 | * Generates KEY_WWAN, KEY_WLAN, KEY_BLUETOOTH, SW_RFKILL_ALL, and |
| 136 | other such events when the user presses certain keys, buttons, or |
| 137 | toggles certain physical switches. |
| 138 | |
| 139 | THE INPUT LAYER IS NEVER USED TO PROPAGATE STATUS, NOTIFICATIONS OR THE |
| 140 | KIND OF STUFF AN ON-SCREEN-DISPLAY APPLICATION WOULD REPORT. It is |
| 141 | used to issue *commands* for the system to change behaviour, and these |
| 142 | commands may or may not be carried out by some kernel driver or |
| 143 | userspace application. It follows that doing user feedback based only |
Henrique de Moraes Holschuh | f7983f7 | 2008-06-23 17:46:43 -0300 | [diff] [blame] | 144 | on input events is broken, as there is no guarantee that an input event |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 145 | will be acted upon. |
| 146 | |
| 147 | Most wireless communication device drivers implementing rfkill |
| 148 | functionality MUST NOT generate these events, and have no reason to |
Henrique de Moraes Holschuh | f7983f7 | 2008-06-23 17:46:43 -0300 | [diff] [blame] | 149 | register themselves with the input layer. Doing otherwise is a common |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 150 | misconception. There is an API to propagate rfkill status change |
| 151 | information, and it is NOT the input layer. |
| 152 | |
| 153 | rfkill class: |
| 154 | |
| 155 | * Calls a hook in a driver to effectively change the wireless |
| 156 | transmitter state; |
| 157 | * Keeps track of the wireless transmitter state (with help from |
| 158 | the driver); |
| 159 | * Generates userspace notifications (uevents) and a call to a |
| 160 | notification chain (kernel) when there is a wireless transmitter |
| 161 | state change; |
| 162 | * Connects a wireless communications driver with the common rfkill |
| 163 | control system, which, for example, allows actions such as |
| 164 | "switch all bluetooth devices offline" to be carried out by |
| 165 | userspace or by rfkill-input. |
| 166 | |
| 167 | THE RFKILL CLASS NEVER ISSUES INPUT EVENTS. THE RFKILL CLASS DOES |
| 168 | NOT LISTEN TO INPUT EVENTS. NO DRIVER USING THE RFKILL CLASS SHALL |
Henrique de Moraes Holschuh | f7983f7 | 2008-06-23 17:46:43 -0300 | [diff] [blame] | 169 | EVER LISTEN TO, OR ACT ON RFKILL INPUT EVENTS. Doing otherwise is |
| 170 | a layering violation. |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 171 | |
| 172 | Most wireless data communication drivers in the kernel have just to |
| 173 | implement the rfkill class API to work properly. Interfacing to the |
Henrique de Moraes Holschuh | f7983f7 | 2008-06-23 17:46:43 -0300 | [diff] [blame] | 174 | input layer is not often required (and is very often a *bug*) on |
| 175 | wireless drivers. |
| 176 | |
| 177 | Platform drivers often have to attach to the input layer to *issue* |
| 178 | (but never to listen to) rfkill events for rfkill switches, and also to |
| 179 | the rfkill class to export a control interface for the platform rfkill |
| 180 | controllers to the rfkill subsystem. This does NOT mean the rfkill |
| 181 | switch is attached to a rfkill class (doing so is almost always wrong). |
| 182 | It just means the same kernel module is the driver for different |
| 183 | devices (rfkill switches and rfkill controllers). |
| 184 | |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 185 | |
| 186 | Userspace input handlers (uevents) or kernel input handlers (rfkill-input): |
| 187 | |
| 188 | * Implements the policy of what should happen when one of the input |
| 189 | layer events related to rfkill operation is received. |
| 190 | * Uses the sysfs interface (userspace) or private rfkill API calls |
| 191 | to tell the devices registered with the rfkill class to change |
| 192 | their state (i.e. translates the input layer event into real |
| 193 | action). |
| 194 | * rfkill-input implements EPO by handling EV_SW SW_RFKILL_ALL 0 |
| 195 | (power off all transmitters) in a special way: it ignores any |
Henrique de Moraes Holschuh | 5005657 | 2008-06-23 17:46:42 -0300 | [diff] [blame] | 196 | overrides and local state cache and forces all transmitters to the |
| 197 | RFKILL_STATE_SOFT_BLOCKED state (including those which are already |
| 198 | supposed to be BLOCKED). Note that the opposite event (power on all |
| 199 | transmitters) is handled normally. |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 200 | |
| 201 | Userspace uevent handler or kernel platform-specific drivers hooked to the |
| 202 | rfkill notifier chain: |
| 203 | |
| 204 | * Taps into the rfkill notifier chain or to KOBJ_CHANGE uevents, |
| 205 | in order to know when a device that is registered with the rfkill |
| 206 | class changes state; |
| 207 | * Issues feedback notifications to the user; |
| 208 | * In the rare platforms where this is required, synthesizes an input |
| 209 | event to command all *OTHER* rfkill devices to also change their |
| 210 | statues when a specific rfkill device changes state. |
| 211 | |
| 212 | |
| 213 | =============================================================================== |
| 214 | 3: Kernel driver guidelines |
| 215 | |
Henrique de Moraes Holschuh | f7983f7 | 2008-06-23 17:46:43 -0300 | [diff] [blame] | 216 | Remember: point-of-view is everything for a driver that connects to the rfkill |
| 217 | subsystem. All the details below must be measured/perceived from the point of |
| 218 | view of the specific driver being modified. |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 219 | |
Henrique de Moraes Holschuh | f7983f7 | 2008-06-23 17:46:43 -0300 | [diff] [blame] | 220 | The first thing one needs to know is whether his driver should be talking to |
| 221 | the rfkill class or to the input layer. In rare cases (platform drivers), it |
| 222 | could happen that you need to do both, as platform drivers often handle a |
| 223 | variety of devices in the same driver. |
| 224 | |
| 225 | Do not mistake input devices for rfkill controllers. The only type of "rfkill |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 226 | switch" device that is to be registered with the rfkill class are those |
| 227 | directly controlling the circuits that cause a wireless transmitter to stop |
Henrique de Moraes Holschuh | f7983f7 | 2008-06-23 17:46:43 -0300 | [diff] [blame] | 228 | working (or the software equivalent of them), i.e. what we call a rfkill |
| 229 | controller. Every other kind of "rfkill switch" is just an input device and |
| 230 | MUST NOT be registered with the rfkill class. |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 231 | |
| 232 | A driver should register a device with the rfkill class when ALL of the |
Henrique de Moraes Holschuh | f7983f7 | 2008-06-23 17:46:43 -0300 | [diff] [blame] | 233 | following conditions are met (they define a rfkill controller): |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 234 | |
| 235 | 1. The device is/controls a data communications wireless transmitter; |
| 236 | |
| 237 | 2. The kernel can interact with the hardware/firmware to CHANGE the wireless |
| 238 | transmitter state (block/unblock TX operation); |
| 239 | |
Henrique de Moraes Holschuh | f7983f7 | 2008-06-23 17:46:43 -0300 | [diff] [blame] | 240 | 3. The transmitter can be made to not emit any energy when "blocked": |
| 241 | rfkill is not about blocking data transmissions, it is about blocking |
| 242 | energy emission; |
| 243 | |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 244 | A driver should register a device with the input subsystem to issue |
| 245 | rfkill-related events (KEY_WLAN, KEY_BLUETOOTH, KEY_WWAN, KEY_WIMAX, |
| 246 | SW_RFKILL_ALL, etc) when ALL of the folowing conditions are met: |
| 247 | |
| 248 | 1. It is directly related to some physical device the user interacts with, to |
| 249 | command the O.S./firmware/hardware to enable/disable a data communications |
| 250 | wireless transmitter. |
| 251 | |
| 252 | Examples of the physical device are: buttons, keys and switches the user |
| 253 | will press/touch/slide/switch to enable or disable the wireless |
| 254 | communication device. |
| 255 | |
| 256 | 2. It is NOT slaved to another device, i.e. there is no other device that |
| 257 | issues rfkill-related input events in preference to this one. |
| 258 | |
Henrique de Moraes Holschuh | f7983f7 | 2008-06-23 17:46:43 -0300 | [diff] [blame] | 259 | Please refer to the corner cases and examples section for more details. |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 260 | |
| 261 | When in doubt, do not issue input events. For drivers that should generate |
| 262 | input events in some platforms, but not in others (e.g. b43), the best solution |
| 263 | is to NEVER generate input events in the first place. That work should be |
| 264 | deferred to a platform-specific kernel module (which will know when to generate |
| 265 | events through the rfkill notifier chain) or to userspace. This avoids the |
| 266 | usual maintenance problems with DMI whitelisting. |
| 267 | |
| 268 | |
| 269 | Corner cases and examples: |
Ivo van Doorn | dac24ab | 2007-09-13 09:22:55 +0200 | [diff] [blame] | 270 | ==================================== |
Ivo van Doorn | dac24ab | 2007-09-13 09:22:55 +0200 | [diff] [blame] | 271 | |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 272 | 1. If the device is an input device that, because of hardware or firmware, |
| 273 | causes wireless transmitters to be blocked regardless of the kernel's will, it |
| 274 | is still just an input device, and NOT to be registered with the rfkill class. |
Ivo van Doorn | dac24ab | 2007-09-13 09:22:55 +0200 | [diff] [blame] | 275 | |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 276 | 2. If the wireless transmitter switch control is read-only, it is an input |
| 277 | device and not to be registered with the rfkill class (and maybe not to be made |
| 278 | an input layer event source either, see below). |
Ivo van Doorn | dac24ab | 2007-09-13 09:22:55 +0200 | [diff] [blame] | 279 | |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 280 | 3. If there is some other device driver *closer* to the actual hardware the |
| 281 | user interacted with (the button/switch/key) to issue an input event, THAT is |
| 282 | the device driver that should be issuing input events. |
Ivo van Doorn | dac24ab | 2007-09-13 09:22:55 +0200 | [diff] [blame] | 283 | |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 284 | E.g: |
| 285 | [RFKILL slider switch] -- [GPIO hardware] -- [WLAN card rf-kill input] |
| 286 | (platform driver) (wireless card driver) |
Ivo van Doorn | dac24ab | 2007-09-13 09:22:55 +0200 | [diff] [blame] | 287 | |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 288 | The user is closer to the RFKILL slide switch plaform driver, so the driver |
| 289 | which must issue input events is the platform driver looking at the GPIO |
| 290 | hardware, and NEVER the wireless card driver (which is just a slave). It is |
| 291 | very likely that there are other leaves than just the WLAN card rf-kill input |
| 292 | (e.g. a bluetooth card, etc)... |
Ivo van Doorn | dac24ab | 2007-09-13 09:22:55 +0200 | [diff] [blame] | 293 | |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 294 | On the other hand, some embedded devices do this: |
Ivo van Doorn | dac24ab | 2007-09-13 09:22:55 +0200 | [diff] [blame] | 295 | |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 296 | [RFKILL slider switch] -- [WLAN card rf-kill input] |
| 297 | (wireless card driver) |
Ivo van Doorn | dac24ab | 2007-09-13 09:22:55 +0200 | [diff] [blame] | 298 | |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 299 | In this situation, the wireless card driver *could* register itself as an input |
| 300 | device and issue rf-kill related input events... but in order to AVOID the need |
| 301 | for DMI whitelisting, the wireless card driver does NOT do it. Userspace (HAL) |
| 302 | or a platform driver (that exists only on these embedded devices) will do the |
| 303 | dirty job of issuing the input events. |
| 304 | |
| 305 | |
| 306 | COMMON MISTAKES in kernel drivers, related to rfkill: |
Ivo van Doorn | dac24ab | 2007-09-13 09:22:55 +0200 | [diff] [blame] | 307 | ==================================== |
Ivo van Doorn | dac24ab | 2007-09-13 09:22:55 +0200 | [diff] [blame] | 308 | |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 309 | 1. NEVER confuse input device keys and buttons with input device switches. |
| 310 | |
| 311 | 1a. Switches are always set or reset. They report the current state |
| 312 | (on position or off position). |
| 313 | |
| 314 | 1b. Keys and buttons are either in the pressed or not-pressed state, and |
| 315 | that's it. A "button" that latches down when you press it, and |
| 316 | unlatches when you press it again is in fact a switch as far as input |
| 317 | devices go. |
| 318 | |
| 319 | Add the SW_* events you need for switches, do NOT try to emulate a button using |
| 320 | KEY_* events just because there is no such SW_* event yet. Do NOT try to use, |
| 321 | for example, KEY_BLUETOOTH when you should be using SW_BLUETOOTH instead. |
| 322 | |
Henrique de Moraes Holschuh | f7983f7 | 2008-06-23 17:46:43 -0300 | [diff] [blame] | 323 | 2. Input device switches (sources of EV_SW events) DO store their current state |
| 324 | (so you *must* initialize it by issuing a gratuitous input layer event on |
| 325 | driver start-up and also when resuming from sleep), and that state CAN be |
| 326 | queried from userspace through IOCTLs. There is no sysfs interface for this, |
| 327 | but that doesn't mean you should break things trying to hook it to the rfkill |
| 328 | class to get a sysfs interface :-) |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 329 | |
Henrique de Moraes Holschuh | f7983f7 | 2008-06-23 17:46:43 -0300 | [diff] [blame] | 330 | 3. Do not issue *_RFKILL_ALL events by default, unless you are sure it is the |
| 331 | correct event for your switch/button. These events are emergency power-off |
| 332 | events when they are trying to turn the transmitters off. An example of an |
| 333 | input device which SHOULD generate *_RFKILL_ALL events is the wireless-kill |
| 334 | switch in a laptop which is NOT a hotkey, but a real switch that kills radios |
| 335 | in hardware, even if the O.S. has gone to lunch. An example of an input device |
| 336 | which SHOULD NOT generate *_RFKILL_ALL events by default, is any sort of hot |
| 337 | key that does nothing by itself, as well as any hot key that is type-specific |
| 338 | (e.g. the one for WLAN). |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 339 | |
| 340 | |
Henrique de Moraes Holschuh | f7983f7 | 2008-06-23 17:46:43 -0300 | [diff] [blame] | 341 | 3.1 Guidelines for wireless device drivers |
| 342 | ------------------------------------------ |
| 343 | |
Henrique de Moraes Holschuh | bed7aac | 2008-08-26 11:58:01 -0300 | [diff] [blame^] | 344 | (in this text, rfkill->foo means the foo field of struct rfkill). |
| 345 | |
Henrique de Moraes Holschuh | f7983f7 | 2008-06-23 17:46:43 -0300 | [diff] [blame] | 346 | 1. Each independent transmitter in a wireless device (usually there is only one |
| 347 | transmitter per device) should have a SINGLE rfkill class attached to it. |
| 348 | |
| 349 | 2. If the device does not have any sort of hardware assistance to allow the |
| 350 | driver to rfkill the device, the driver should emulate it by taking all actions |
| 351 | required to silence the transmitter. |
| 352 | |
| 353 | 3. If it is impossible to silence the transmitter (i.e. it still emits energy, |
| 354 | even if it is just in brief pulses, when there is no data to transmit and there |
| 355 | is no hardware support to turn it off) do NOT lie to the users. Do not attach |
| 356 | it to a rfkill class. The rfkill subsystem does not deal with data |
| 357 | transmission, it deals with energy emission. If the transmitter is emitting |
| 358 | energy, it is not blocked in rfkill terms. |
| 359 | |
| 360 | 4. It doesn't matter if the device has multiple rfkill input lines affecting |
| 361 | the same transmitter, their combined state is to be exported as a single state |
| 362 | per transmitter (see rule 1). |
| 363 | |
| 364 | This rule exists because users of the rfkill subsystem expect to get (and set, |
| 365 | when possible) the overall transmitter rfkill state, not of a particular rfkill |
| 366 | line. |
| 367 | |
Henrique de Moraes Holschuh | bed7aac | 2008-08-26 11:58:01 -0300 | [diff] [blame^] | 368 | 5. The wireless device driver MUST NOT leave the transmitter enabled during |
| 369 | suspend and hibernation unless: |
| 370 | |
| 371 | 5.1. The transmitter has to be enabled for some sort of functionality |
| 372 | like wake-on-wireless-packet or autonomous packed forwarding in a mesh |
| 373 | network, and that functionality is enabled for this suspend/hibernation |
| 374 | cycle. |
| 375 | |
| 376 | AND |
| 377 | |
| 378 | 5.2. The device was not on a user-requested BLOCKED state before |
| 379 | the suspend (i.e. the driver must NOT unblock a device, not even |
| 380 | to support wake-on-wireless-packet or remain in the mesh). |
| 381 | |
| 382 | In other words, there is absolutely no allowed scenario where a driver can |
| 383 | automatically take action to unblock a rfkill controller (obviously, this deals |
| 384 | with scenarios where soft-blocking or both soft and hard blocking is happening. |
| 385 | Scenarios where hardware rfkill lines are the only ones blocking the |
| 386 | transmitter are outside of this rule, since the wireless device driver does not |
| 387 | control its input hardware rfkill lines in the first place). |
| 388 | |
| 389 | 6. During resume, rfkill will try to restore its previous state. |
| 390 | |
| 391 | 7. After a rfkill class is suspended, it will *not* call rfkill->toggle_radio |
| 392 | until it is resumed. |
| 393 | |
Henrique de Moraes Holschuh | e10e0df | 2008-08-02 14:56:25 -0300 | [diff] [blame] | 394 | |
Henrique de Moraes Holschuh | f7983f7 | 2008-06-23 17:46:43 -0300 | [diff] [blame] | 395 | Example of a WLAN wireless driver connected to the rfkill subsystem: |
| 396 | -------------------------------------------------------------------- |
| 397 | |
| 398 | A certain WLAN card has one input pin that causes it to block the transmitter |
| 399 | and makes the status of that input pin available (only for reading!) to the |
| 400 | kernel driver. This is a hard rfkill input line (it cannot be overridden by |
| 401 | the kernel driver). |
| 402 | |
| 403 | The card also has one PCI register that, if manipulated by the driver, causes |
| 404 | it to block the transmitter. This is a soft rfkill input line. |
| 405 | |
| 406 | It has also a thermal protection circuitry that shuts down its transmitter if |
| 407 | the card overheats, and makes the status of that protection available (only for |
| 408 | reading!) to the kernel driver. This is also a hard rfkill input line. |
| 409 | |
| 410 | If either one of these rfkill lines are active, the transmitter is blocked by |
| 411 | the hardware and forced offline. |
| 412 | |
| 413 | The driver should allocate and attach to its struct device *ONE* instance of |
| 414 | the rfkill class (there is only one transmitter). |
| 415 | |
| 416 | It can implement the get_state() hook, and return RFKILL_STATE_HARD_BLOCKED if |
| 417 | either one of its two hard rfkill input lines are active. If the two hard |
| 418 | rfkill lines are inactive, it must return RFKILL_STATE_SOFT_BLOCKED if its soft |
| 419 | rfkill input line is active. Only if none of the rfkill input lines are |
| 420 | active, will it return RFKILL_STATE_UNBLOCKED. |
| 421 | |
Henrique de Moraes Holschuh | 2fd9b22 | 2008-07-21 21:18:17 -0300 | [diff] [blame] | 422 | Since the device has a hardware rfkill line, it IS subject to state changes |
| 423 | external to rfkill. Therefore, the driver must make sure that it calls |
| 424 | rfkill_force_state() to keep the status always up-to-date, and it must do a |
| 425 | rfkill_force_state() on resume from sleep. |
Henrique de Moraes Holschuh | f7983f7 | 2008-06-23 17:46:43 -0300 | [diff] [blame] | 426 | |
| 427 | Every time the driver gets a notification from the card that one of its rfkill |
| 428 | lines changed state (polling might be needed on badly designed cards that don't |
| 429 | generate interrupts for such events), it recomputes the rfkill state as per |
| 430 | above, and calls rfkill_force_state() to update it. |
| 431 | |
| 432 | The driver should implement the toggle_radio() hook, that: |
| 433 | |
| 434 | 1. Returns an error if one of the hardware rfkill lines are active, and the |
| 435 | caller asked for RFKILL_STATE_UNBLOCKED. |
| 436 | |
| 437 | 2. Activates the soft rfkill line if the caller asked for state |
| 438 | RFKILL_STATE_SOFT_BLOCKED. It should do this even if one of the hard rfkill |
| 439 | lines are active, effectively double-blocking the transmitter. |
| 440 | |
| 441 | 3. Deactivates the soft rfkill line if none of the hardware rfkill lines are |
| 442 | active and the caller asked for RFKILL_STATE_UNBLOCKED. |
| 443 | |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 444 | =============================================================================== |
| 445 | 4: Kernel API |
| 446 | |
| 447 | To build a driver with rfkill subsystem support, the driver should depend on |
Henrique de Moraes Holschuh | f7983f7 | 2008-06-23 17:46:43 -0300 | [diff] [blame] | 448 | (or select) the Kconfig symbol RFKILL; it should _not_ depend on RKFILL_INPUT. |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 449 | |
| 450 | The hardware the driver talks to may be write-only (where the current state |
| 451 | of the hardware is unknown), or read-write (where the hardware can be queried |
| 452 | about its current state). |
| 453 | |
| 454 | The rfkill class will call the get_state hook of a device every time it needs |
Henrique de Moraes Holschuh | 2fd9b22 | 2008-07-21 21:18:17 -0300 | [diff] [blame] | 455 | to know the *real* current state of the hardware. This can happen often, but |
| 456 | it does not do any polling, so it is not enough on hardware that is subject |
| 457 | to state changes outside of the rfkill subsystem. |
| 458 | |
| 459 | Therefore, calling rfkill_force_state() when a state change happens is |
| 460 | mandatory when the device has a hardware rfkill line, or when something else |
| 461 | like the firmware could cause its state to be changed without going through the |
| 462 | rfkill class. |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 463 | |
| 464 | Some hardware provides events when its status changes. In these cases, it is |
| 465 | best for the driver to not provide a get_state hook, and instead register the |
| 466 | rfkill class *already* with the correct status, and keep it updated using |
| 467 | rfkill_force_state() when it gets an event from the hardware. |
| 468 | |
Henrique de Moraes Holschuh | 2fd9b22 | 2008-07-21 21:18:17 -0300 | [diff] [blame] | 469 | rfkill_force_state() must be used on the device resume handlers to update the |
| 470 | rfkill status, should there be any chance of the device status changing during |
| 471 | the sleep. |
| 472 | |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 473 | There is no provision for a statically-allocated rfkill struct. You must |
| 474 | use rfkill_allocate() to allocate one. |
| 475 | |
| 476 | You should: |
| 477 | - rfkill_allocate() |
| 478 | - modify rfkill fields (flags, name) |
| 479 | - modify state to the current hardware state (THIS IS THE ONLY TIME |
| 480 | YOU CAN ACCESS state DIRECTLY) |
| 481 | - rfkill_register() |
| 482 | |
Henrique de Moraes Holschuh | 5005657 | 2008-06-23 17:46:42 -0300 | [diff] [blame] | 483 | The only way to set a device to the RFKILL_STATE_HARD_BLOCKED state is through |
| 484 | a suitable return of get_state() or through rfkill_force_state(). |
| 485 | |
| 486 | When a device is in the RFKILL_STATE_HARD_BLOCKED state, the only way to switch |
| 487 | it to a different state is through a suitable return of get_state() or through |
| 488 | rfkill_force_state(). |
| 489 | |
| 490 | If toggle_radio() is called to set a device to state RFKILL_STATE_SOFT_BLOCKED |
| 491 | when that device is already at the RFKILL_STATE_HARD_BLOCKED state, it should |
| 492 | not return an error. Instead, it should try to double-block the transmitter, |
| 493 | so that its state will change from RFKILL_STATE_HARD_BLOCKED to |
| 494 | RFKILL_STATE_SOFT_BLOCKED should the hardware blocking cease. |
| 495 | |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 496 | Please refer to the source for more documentation. |
| 497 | |
| 498 | =============================================================================== |
| 499 | 5: Userspace support |
| 500 | |
| 501 | rfkill devices issue uevents (with an action of "change"), with the following |
| 502 | environment variables set: |
| 503 | |
| 504 | RFKILL_NAME |
| 505 | RFKILL_STATE |
| 506 | RFKILL_TYPE |
| 507 | |
| 508 | The ABI for these variables is defined by the sysfs attributes. It is best |
| 509 | to take a quick look at the source to make sure of the possible values. |
| 510 | |
| 511 | It is expected that HAL will trap those, and bridge them to DBUS, etc. These |
| 512 | events CAN and SHOULD be used to give feedback to the user about the rfkill |
| 513 | status of the system. |
| 514 | |
| 515 | Input devices may issue events that are related to rfkill. These are the |
| 516 | various KEY_* events and SW_* events supported by rfkill-input.c. |
| 517 | |
| 518 | ******IMPORTANT****** |
| 519 | When rfkill-input is ACTIVE, userspace is NOT TO CHANGE THE STATE OF AN RFKILL |
| 520 | SWITCH IN RESPONSE TO AN INPUT EVENT also handled by rfkill-input, unless it |
| 521 | has set to true the user_claim attribute for that particular switch. This rule |
| 522 | is *absolute*; do NOT violate it. |
| 523 | ******IMPORTANT****** |
| 524 | |
| 525 | Userspace must not assume it is the only source of control for rfkill switches. |
Henrique de Moraes Holschuh | f7983f7 | 2008-06-23 17:46:43 -0300 | [diff] [blame] | 526 | Their state CAN and WILL change due to firmware actions, direct user actions, |
| 527 | and the rfkill-input EPO override for *_RFKILL_ALL. |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 528 | |
Henrique de Moraes Holschuh | f7983f7 | 2008-06-23 17:46:43 -0300 | [diff] [blame] | 529 | When rfkill-input is not active, userspace must initiate a rfkill status |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 530 | change by writing to the "state" attribute in order for anything to happen. |
| 531 | |
| 532 | Take particular care to implement EV_SW SW_RFKILL_ALL properly. When that |
| 533 | switch is set to OFF, *every* rfkill device *MUST* be immediately put into the |
Henrique de Moraes Holschuh | 5005657 | 2008-06-23 17:46:42 -0300 | [diff] [blame] | 534 | RFKILL_STATE_SOFT_BLOCKED state, no questions asked. |
Ivo van Doorn | dac24ab | 2007-09-13 09:22:55 +0200 | [diff] [blame] | 535 | |
| 536 | The following sysfs entries will be created: |
| 537 | |
| 538 | name: Name assigned by driver to this key (interface or driver name). |
| 539 | type: Name of the key type ("wlan", "bluetooth", etc). |
Henrique de Moraes Holschuh | 5005657 | 2008-06-23 17:46:42 -0300 | [diff] [blame] | 540 | state: Current state of the transmitter |
| 541 | 0: RFKILL_STATE_SOFT_BLOCKED |
Henrique de Moraes Holschuh | f7983f7 | 2008-06-23 17:46:43 -0300 | [diff] [blame] | 542 | transmitter is forced off, but one can override it |
| 543 | by a write to the state attribute; |
Henrique de Moraes Holschuh | 5005657 | 2008-06-23 17:46:42 -0300 | [diff] [blame] | 544 | 1: RFKILL_STATE_UNBLOCKED |
| 545 | transmiter is NOT forced off, and may operate if |
| 546 | all other conditions for such operation are met |
Henrique de Moraes Holschuh | f7983f7 | 2008-06-23 17:46:43 -0300 | [diff] [blame] | 547 | (such as interface is up and configured, etc); |
Henrique de Moraes Holschuh | 5005657 | 2008-06-23 17:46:42 -0300 | [diff] [blame] | 548 | 2: RFKILL_STATE_HARD_BLOCKED |
| 549 | transmitter is forced off by something outside of |
Henrique de Moraes Holschuh | f7983f7 | 2008-06-23 17:46:43 -0300 | [diff] [blame] | 550 | the driver's control. One cannot set a device to |
| 551 | this state through writes to the state attribute; |
Ivo van Doorn | dac24ab | 2007-09-13 09:22:55 +0200 | [diff] [blame] | 552 | claim: 1: Userspace handles events, 0: Kernel handles events |
| 553 | |
| 554 | Both the "state" and "claim" entries are also writable. For the "state" entry |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 555 | this means that when 1 or 0 is written, the device rfkill state (if not yet in |
| 556 | the requested state), will be will be toggled accordingly. |
| 557 | |
Ivo van Doorn | dac24ab | 2007-09-13 09:22:55 +0200 | [diff] [blame] | 558 | For the "claim" entry writing 1 to it means that the kernel no longer handles |
| 559 | key events even though RFKILL_INPUT input was enabled. When "claim" has been |
| 560 | set to 0, userspace should make sure that it listens for the input events or |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame] | 561 | check the sysfs "state" entry regularly to correctly perform the required tasks |
| 562 | when the rkfill key is pressed. |
| 563 | |
| 564 | A note about input devices and EV_SW events: |
| 565 | |
| 566 | In order to know the current state of an input device switch (like |
| 567 | SW_RFKILL_ALL), you will need to use an IOCTL. That information is not |
| 568 | available through sysfs in a generic way at this time, and it is not available |
| 569 | through the rfkill class AT ALL. |