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 |
| 7 | 4 Kernel API |
| 8 | 5 Userspace support |
Ivo van Doorn | dac24ab | 2007-09-13 09:22:55 +0200 | [diff] [blame] | 9 | |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame^] | 10 | |
| 11 | 1. Introduction: |
Ivo van Doorn | dac24ab | 2007-09-13 09:22:55 +0200 | [diff] [blame] | 12 | |
Henrique de Moraes Holschuh | f3146af | 2008-06-23 17:22:56 -0300 | [diff] [blame] | 13 | 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^] | 14 | can enable or disable the signal output of a wireless *transmitter* of any |
| 15 | 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] | 16 | |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame^] | 17 | The rfkill switch subsystem offers support for keys and switches often found on |
| 18 | laptops to enable wireless devices like WiFi and Bluetooth to actually perform |
| 19 | an action. |
Henrique de Moraes Holschuh | f3146af | 2008-06-23 17:22:56 -0300 | [diff] [blame] | 20 | |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame^] | 21 | 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] | 22 | 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^] | 23 | radio-frequency transmitters _must_ be disabled (e.g. airplanes). |
| 24 | |
| 25 | Because of this requirement, userspace support for the keys should not be made |
| 26 | mandatory. Because userspace might want to perform some additional smarter |
| 27 | tasks when the key is pressed, rfkill provides userspace the possibility to |
| 28 | take over the task to handle the key events. |
| 29 | |
| 30 | =============================================================================== |
| 31 | 2: Implementation details |
| 32 | |
| 33 | The rfkill class provides kernel drivers with an interface that allows them to |
| 34 | know when they should enable or disable a wireless network device transmitter. |
| 35 | |
| 36 | The rfkill-input module provides the kernel with the ability to implement a |
| 37 | basic response when the user presses a key or button (or toggles a switch) |
| 38 | related to rfkill functionality. It is an in-kernel implementation of default |
| 39 | policy of reacting to rfkill-related input events and neither mandatory nor |
| 40 | required for wireless drivers to operate. |
| 41 | |
| 42 | The rfkill-input module also provides EPO (emergency power-off) functionality |
| 43 | for all wireless transmitters. This function cannot be overriden, and it is |
| 44 | always active. rfkill EPO is related to *_RFKILL_ALL input events. |
| 45 | |
| 46 | All state changes on rfkill devices are propagated by the rfkill class to a |
| 47 | notification chain and also to userspace through uevents. |
Ivo van Doorn | dac24ab | 2007-09-13 09:22:55 +0200 | [diff] [blame] | 48 | |
| 49 | The system inside the kernel has been split into 2 separate sections: |
| 50 | 1 - RFKILL |
| 51 | 2 - RFKILL_INPUT |
| 52 | |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame^] | 53 | The first option enables rfkill support and will make sure userspace will be |
| 54 | notified of any events through uevents. It provides a notification chain for |
| 55 | interested parties in the kernel to also get notified of rfkill state changes |
| 56 | in other drivers. It creates several sysfs entries which can be used by |
| 57 | userspace. See section "Userspace support". |
Ivo van Doorn | dac24ab | 2007-09-13 09:22:55 +0200 | [diff] [blame] | 58 | |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame^] | 59 | The second option provides an rfkill input handler. This handler will listen to |
| 60 | all rfkill key events and will toggle the radio accordingly. With this option |
| 61 | enabled userspace could either do nothing or simply perform monitoring tasks. |
Ivo van Doorn | dac24ab | 2007-09-13 09:22:55 +0200 | [diff] [blame] | 62 | |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame^] | 63 | When a rfkill switch is in the RFKILL_STATE_ON, the wireless transmitter (radio |
| 64 | TX circuit for example) is *enabled*. When the rfkill switch is in the |
| 65 | RFKILL_STATE_OFF, the wireless transmitter is to be *blocked* from operating. |
| 66 | |
| 67 | Full rfkill functionality requires two different subsystems to cooperate: the |
| 68 | input layer and the rfkill class. The input layer issues *commands* to the |
| 69 | entire system requesting that devices registered to the rfkill class change |
| 70 | state. The way this interaction happens is not complex, but it is not obvious |
| 71 | either: |
| 72 | |
| 73 | Kernel Input layer: |
| 74 | |
| 75 | * Generates KEY_WWAN, KEY_WLAN, KEY_BLUETOOTH, SW_RFKILL_ALL, and |
| 76 | other such events when the user presses certain keys, buttons, or |
| 77 | toggles certain physical switches. |
| 78 | |
| 79 | THE INPUT LAYER IS NEVER USED TO PROPAGATE STATUS, NOTIFICATIONS OR THE |
| 80 | KIND OF STUFF AN ON-SCREEN-DISPLAY APPLICATION WOULD REPORT. It is |
| 81 | used to issue *commands* for the system to change behaviour, and these |
| 82 | commands may or may not be carried out by some kernel driver or |
| 83 | userspace application. It follows that doing user feedback based only |
| 84 | on input events is broken, there is no guarantee that an input event |
| 85 | will be acted upon. |
| 86 | |
| 87 | Most wireless communication device drivers implementing rfkill |
| 88 | functionality MUST NOT generate these events, and have no reason to |
| 89 | register themselves with the input layer. This is a common |
| 90 | misconception. There is an API to propagate rfkill status change |
| 91 | information, and it is NOT the input layer. |
| 92 | |
| 93 | rfkill class: |
| 94 | |
| 95 | * Calls a hook in a driver to effectively change the wireless |
| 96 | transmitter state; |
| 97 | * Keeps track of the wireless transmitter state (with help from |
| 98 | the driver); |
| 99 | * Generates userspace notifications (uevents) and a call to a |
| 100 | notification chain (kernel) when there is a wireless transmitter |
| 101 | state change; |
| 102 | * Connects a wireless communications driver with the common rfkill |
| 103 | control system, which, for example, allows actions such as |
| 104 | "switch all bluetooth devices offline" to be carried out by |
| 105 | userspace or by rfkill-input. |
| 106 | |
| 107 | THE RFKILL CLASS NEVER ISSUES INPUT EVENTS. THE RFKILL CLASS DOES |
| 108 | NOT LISTEN TO INPUT EVENTS. NO DRIVER USING THE RFKILL CLASS SHALL |
| 109 | EVER LISTEN TO, OR ACT ON RFKILL INPUT EVENTS. |
| 110 | |
| 111 | Most wireless data communication drivers in the kernel have just to |
| 112 | implement the rfkill class API to work properly. Interfacing to the |
| 113 | input layer is not often required (and is very often a *bug*). |
| 114 | |
| 115 | Userspace input handlers (uevents) or kernel input handlers (rfkill-input): |
| 116 | |
| 117 | * Implements the policy of what should happen when one of the input |
| 118 | layer events related to rfkill operation is received. |
| 119 | * Uses the sysfs interface (userspace) or private rfkill API calls |
| 120 | to tell the devices registered with the rfkill class to change |
| 121 | their state (i.e. translates the input layer event into real |
| 122 | action). |
| 123 | * rfkill-input implements EPO by handling EV_SW SW_RFKILL_ALL 0 |
| 124 | (power off all transmitters) in a special way: it ignores any |
| 125 | overrides and local state cache and forces all transmitters to |
| 126 | the OFF state (including those which are already supposed to be |
| 127 | OFF). Note that the opposite event (power on all transmitters) |
| 128 | is handled normally. |
| 129 | |
| 130 | Userspace uevent handler or kernel platform-specific drivers hooked to the |
| 131 | rfkill notifier chain: |
| 132 | |
| 133 | * Taps into the rfkill notifier chain or to KOBJ_CHANGE uevents, |
| 134 | in order to know when a device that is registered with the rfkill |
| 135 | class changes state; |
| 136 | * Issues feedback notifications to the user; |
| 137 | * In the rare platforms where this is required, synthesizes an input |
| 138 | event to command all *OTHER* rfkill devices to also change their |
| 139 | statues when a specific rfkill device changes state. |
| 140 | |
| 141 | |
| 142 | =============================================================================== |
| 143 | 3: Kernel driver guidelines |
| 144 | |
| 145 | The first thing one needs to know is whether his driver should be talking to |
| 146 | the rfkill class or to the input layer. |
| 147 | |
| 148 | Do not mistake input devices for rfkill devices. The only type of "rfkill |
| 149 | switch" device that is to be registered with the rfkill class are those |
| 150 | directly controlling the circuits that cause a wireless transmitter to stop |
| 151 | working (or the software equivalent of them). Every other kind of "rfkill |
| 152 | switch" is just an input device and MUST NOT be registered with the rfkill |
| 153 | class. |
| 154 | |
| 155 | A driver should register a device with the rfkill class when ALL of the |
| 156 | following conditions are met: |
| 157 | |
| 158 | 1. The device is/controls a data communications wireless transmitter; |
| 159 | |
| 160 | 2. The kernel can interact with the hardware/firmware to CHANGE the wireless |
| 161 | transmitter state (block/unblock TX operation); |
| 162 | |
| 163 | A driver should register a device with the input subsystem to issue |
| 164 | rfkill-related events (KEY_WLAN, KEY_BLUETOOTH, KEY_WWAN, KEY_WIMAX, |
| 165 | SW_RFKILL_ALL, etc) when ALL of the folowing conditions are met: |
| 166 | |
| 167 | 1. It is directly related to some physical device the user interacts with, to |
| 168 | command the O.S./firmware/hardware to enable/disable a data communications |
| 169 | wireless transmitter. |
| 170 | |
| 171 | Examples of the physical device are: buttons, keys and switches the user |
| 172 | will press/touch/slide/switch to enable or disable the wireless |
| 173 | communication device. |
| 174 | |
| 175 | 2. It is NOT slaved to another device, i.e. there is no other device that |
| 176 | issues rfkill-related input events in preference to this one. |
| 177 | |
| 178 | Typically, the ACPI "radio kill" switch of a laptop is the master input |
| 179 | device to issue rfkill events, and, e.g., the WLAN card is just a slave |
| 180 | device that gets disabled by its hardware radio-kill input pin. |
| 181 | |
| 182 | When in doubt, do not issue input events. For drivers that should generate |
| 183 | input events in some platforms, but not in others (e.g. b43), the best solution |
| 184 | is to NEVER generate input events in the first place. That work should be |
| 185 | deferred to a platform-specific kernel module (which will know when to generate |
| 186 | events through the rfkill notifier chain) or to userspace. This avoids the |
| 187 | usual maintenance problems with DMI whitelisting. |
| 188 | |
| 189 | |
| 190 | Corner cases and examples: |
Ivo van Doorn | dac24ab | 2007-09-13 09:22:55 +0200 | [diff] [blame] | 191 | ==================================== |
Ivo van Doorn | dac24ab | 2007-09-13 09:22:55 +0200 | [diff] [blame] | 192 | |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame^] | 193 | 1. If the device is an input device that, because of hardware or firmware, |
| 194 | causes wireless transmitters to be blocked regardless of the kernel's will, it |
| 195 | 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] | 196 | |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame^] | 197 | 2. If the wireless transmitter switch control is read-only, it is an input |
| 198 | device and not to be registered with the rfkill class (and maybe not to be made |
| 199 | an input layer event source either, see below). |
Ivo van Doorn | dac24ab | 2007-09-13 09:22:55 +0200 | [diff] [blame] | 200 | |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame^] | 201 | 3. If there is some other device driver *closer* to the actual hardware the |
| 202 | user interacted with (the button/switch/key) to issue an input event, THAT is |
| 203 | the device driver that should be issuing input events. |
Ivo van Doorn | dac24ab | 2007-09-13 09:22:55 +0200 | [diff] [blame] | 204 | |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame^] | 205 | E.g: |
| 206 | [RFKILL slider switch] -- [GPIO hardware] -- [WLAN card rf-kill input] |
| 207 | (platform driver) (wireless card driver) |
Ivo van Doorn | dac24ab | 2007-09-13 09:22:55 +0200 | [diff] [blame] | 208 | |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame^] | 209 | The user is closer to the RFKILL slide switch plaform driver, so the driver |
| 210 | which must issue input events is the platform driver looking at the GPIO |
| 211 | hardware, and NEVER the wireless card driver (which is just a slave). It is |
| 212 | very likely that there are other leaves than just the WLAN card rf-kill input |
| 213 | (e.g. a bluetooth card, etc)... |
Ivo van Doorn | dac24ab | 2007-09-13 09:22:55 +0200 | [diff] [blame] | 214 | |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame^] | 215 | On the other hand, some embedded devices do this: |
Ivo van Doorn | dac24ab | 2007-09-13 09:22:55 +0200 | [diff] [blame] | 216 | |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame^] | 217 | [RFKILL slider switch] -- [WLAN card rf-kill input] |
| 218 | (wireless card driver) |
Ivo van Doorn | dac24ab | 2007-09-13 09:22:55 +0200 | [diff] [blame] | 219 | |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame^] | 220 | In this situation, the wireless card driver *could* register itself as an input |
| 221 | device and issue rf-kill related input events... but in order to AVOID the need |
| 222 | for DMI whitelisting, the wireless card driver does NOT do it. Userspace (HAL) |
| 223 | or a platform driver (that exists only on these embedded devices) will do the |
| 224 | dirty job of issuing the input events. |
| 225 | |
| 226 | |
| 227 | COMMON MISTAKES in kernel drivers, related to rfkill: |
Ivo van Doorn | dac24ab | 2007-09-13 09:22:55 +0200 | [diff] [blame] | 228 | ==================================== |
Ivo van Doorn | dac24ab | 2007-09-13 09:22:55 +0200 | [diff] [blame] | 229 | |
Henrique de Moraes Holschuh | dc28852 | 2008-06-23 17:23:08 -0300 | [diff] [blame^] | 230 | 1. NEVER confuse input device keys and buttons with input device switches. |
| 231 | |
| 232 | 1a. Switches are always set or reset. They report the current state |
| 233 | (on position or off position). |
| 234 | |
| 235 | 1b. Keys and buttons are either in the pressed or not-pressed state, and |
| 236 | that's it. A "button" that latches down when you press it, and |
| 237 | unlatches when you press it again is in fact a switch as far as input |
| 238 | devices go. |
| 239 | |
| 240 | Add the SW_* events you need for switches, do NOT try to emulate a button using |
| 241 | KEY_* events just because there is no such SW_* event yet. Do NOT try to use, |
| 242 | for example, KEY_BLUETOOTH when you should be using SW_BLUETOOTH instead. |
| 243 | |
| 244 | 2. Input device switches (sources of EV_SW events) DO store their current |
| 245 | state, and that state CAN be queried from userspace through IOCTLs. There is |
| 246 | no sysfs interface for this, but that doesn't mean you should break things |
| 247 | trying to hook it to the rfkill class to get a sysfs interface :-) |
| 248 | |
| 249 | 3. Do not issue *_RFKILL_ALL events, unless you are sure it is the correct |
| 250 | event for your switch/button. These events are emergency power-off events when |
| 251 | they are trying to turn the transmitters off. An example of an input device |
| 252 | which SHOULD generate *_RFKILL_ALL events is the wireless-kill switch in a |
| 253 | laptop which is NOT a hotkey, but a real switch that kills radios in hardware, |
| 254 | even if the O.S. has gone to lunch. An example of an input device which SHOULD |
| 255 | NOT generate *_RFKILL_ALL events is any sort of hot key that does nothing by |
| 256 | itself, as well as any hot key that is type-specific (e.g. the one for WLAN). |
| 257 | |
| 258 | |
| 259 | =============================================================================== |
| 260 | 4: Kernel API |
| 261 | |
| 262 | To build a driver with rfkill subsystem support, the driver should depend on |
| 263 | the Kconfig symbol RFKILL; it should _not_ depend on RKFILL_INPUT. |
| 264 | |
| 265 | The hardware the driver talks to may be write-only (where the current state |
| 266 | of the hardware is unknown), or read-write (where the hardware can be queried |
| 267 | about its current state). |
| 268 | |
| 269 | The rfkill class will call the get_state hook of a device every time it needs |
| 270 | to know the *real* current state of the hardware. This can happen often. |
| 271 | |
| 272 | Some hardware provides events when its status changes. In these cases, it is |
| 273 | best for the driver to not provide a get_state hook, and instead register the |
| 274 | rfkill class *already* with the correct status, and keep it updated using |
| 275 | rfkill_force_state() when it gets an event from the hardware. |
| 276 | |
| 277 | There is no provision for a statically-allocated rfkill struct. You must |
| 278 | use rfkill_allocate() to allocate one. |
| 279 | |
| 280 | You should: |
| 281 | - rfkill_allocate() |
| 282 | - modify rfkill fields (flags, name) |
| 283 | - modify state to the current hardware state (THIS IS THE ONLY TIME |
| 284 | YOU CAN ACCESS state DIRECTLY) |
| 285 | - rfkill_register() |
| 286 | |
| 287 | Please refer to the source for more documentation. |
| 288 | |
| 289 | =============================================================================== |
| 290 | 5: Userspace support |
| 291 | |
| 292 | rfkill devices issue uevents (with an action of "change"), with the following |
| 293 | environment variables set: |
| 294 | |
| 295 | RFKILL_NAME |
| 296 | RFKILL_STATE |
| 297 | RFKILL_TYPE |
| 298 | |
| 299 | The ABI for these variables is defined by the sysfs attributes. It is best |
| 300 | to take a quick look at the source to make sure of the possible values. |
| 301 | |
| 302 | It is expected that HAL will trap those, and bridge them to DBUS, etc. These |
| 303 | events CAN and SHOULD be used to give feedback to the user about the rfkill |
| 304 | status of the system. |
| 305 | |
| 306 | Input devices may issue events that are related to rfkill. These are the |
| 307 | various KEY_* events and SW_* events supported by rfkill-input.c. |
| 308 | |
| 309 | ******IMPORTANT****** |
| 310 | When rfkill-input is ACTIVE, userspace is NOT TO CHANGE THE STATE OF AN RFKILL |
| 311 | SWITCH IN RESPONSE TO AN INPUT EVENT also handled by rfkill-input, unless it |
| 312 | has set to true the user_claim attribute for that particular switch. This rule |
| 313 | is *absolute*; do NOT violate it. |
| 314 | ******IMPORTANT****** |
| 315 | |
| 316 | Userspace must not assume it is the only source of control for rfkill switches. |
| 317 | Their state CAN and WILL change on its own, due to firmware actions, direct |
| 318 | user actions, and the rfkill-input EPO override for *_RFKILL_ALL. |
| 319 | |
| 320 | When rfkill-input is not active, userspace must initiate an rfkill status |
| 321 | change by writing to the "state" attribute in order for anything to happen. |
| 322 | |
| 323 | Take particular care to implement EV_SW SW_RFKILL_ALL properly. When that |
| 324 | switch is set to OFF, *every* rfkill device *MUST* be immediately put into the |
| 325 | OFF state, no questions asked. |
Ivo van Doorn | dac24ab | 2007-09-13 09:22:55 +0200 | [diff] [blame] | 326 | |
| 327 | The following sysfs entries will be created: |
| 328 | |
| 329 | name: Name assigned by driver to this key (interface or driver name). |
| 330 | type: Name of the key type ("wlan", "bluetooth", etc). |
| 331 | state: Current state of the key. 1: On, 0: Off. |
| 332 | claim: 1: Userspace handles events, 0: Kernel handles events |
| 333 | |
| 334 | 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^] | 335 | this means that when 1 or 0 is written, the device rfkill state (if not yet in |
| 336 | the requested state), will be will be toggled accordingly. |
| 337 | |
Ivo van Doorn | dac24ab | 2007-09-13 09:22:55 +0200 | [diff] [blame] | 338 | For the "claim" entry writing 1 to it means that the kernel no longer handles |
| 339 | key events even though RFKILL_INPUT input was enabled. When "claim" has been |
| 340 | 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^] | 341 | check the sysfs "state" entry regularly to correctly perform the required tasks |
| 342 | when the rkfill key is pressed. |
| 343 | |
| 344 | A note about input devices and EV_SW events: |
| 345 | |
| 346 | In order to know the current state of an input device switch (like |
| 347 | SW_RFKILL_ALL), you will need to use an IOCTL. That information is not |
| 348 | available through sysfs in a generic way at this time, and it is not available |
| 349 | through the rfkill class AT ALL. |