Commit | Line | Data |
---|---|---|
dac24ab3 ID |
1 | rfkill - RF switch subsystem support |
2 | ==================================== | |
3 | ||
dc288520 HMH |
4 | 1 Introduction |
5 | 2 Implementation details | |
6 | 3 Kernel driver guidelines | |
7 | 4 Kernel API | |
8 | 5 Userspace support | |
dac24ab3 | 9 | |
dc288520 HMH |
10 | |
11 | 1. Introduction: | |
dac24ab3 | 12 | |
f3146aff | 13 | The rfkill switch subsystem exists to add a generic interface to circuitry that |
dc288520 HMH |
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. | |
f3146aff | 16 | |
dc288520 HMH |
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. | |
f3146aff | 20 | |
dc288520 HMH |
21 | The buttons to enable and disable the wireless transmitters are important in |
22 | situations where the user is for example using his laptop on a location where | |
23 | radio-frequency transmitters _must_ be disabled (e.g. airplanes). | |
dac24ab3 | 24 | |
dc288520 HMH |
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. | |
dac24ab3 | 29 | |
dc288520 HMH |
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. | |
dac24ab3 ID |
48 | |
49 | The system inside the kernel has been split into 2 separate sections: | |
50 | 1 - RFKILL | |
51 | 2 - RFKILL_INPUT | |
52 | ||
dc288520 HMH |
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". | |
58 | ||
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. | |
62 | ||
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. | |
dac24ab3 | 181 | |
dc288520 HMH |
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. | |
dac24ab3 | 188 | |
dc288520 HMH |
189 | |
190 | Corner cases and examples: | |
dac24ab3 | 191 | ==================================== |
dac24ab3 | 192 | |
dc288520 HMH |
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. | |
dac24ab3 | 196 | |
dc288520 HMH |
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). | |
dac24ab3 | 200 | |
dc288520 HMH |
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. | |
dac24ab3 | 204 | |
dc288520 HMH |
205 | E.g: |
206 | [RFKILL slider switch] -- [GPIO hardware] -- [WLAN card rf-kill input] | |
207 | (platform driver) (wireless card driver) | |
208 | ||
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)... | |
214 | ||
215 | On the other hand, some embedded devices do this: | |
216 | ||
217 | [RFKILL slider switch] -- [WLAN card rf-kill input] | |
218 | (wireless card driver) | |
219 | ||
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: | |
228 | ==================================== | |
229 | ||
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. | |
dac24ab3 | 276 | |
dc288520 HMH |
277 | There is no provision for a statically-allocated rfkill struct. You must |
278 | use rfkill_allocate() to allocate one. | |
dac24ab3 | 279 | |
dc288520 | 280 | You should: |
dac24ab3 | 281 | - rfkill_allocate() |
dc288520 HMH |
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) | |
dac24ab3 | 285 | - rfkill_register() |
dac24ab3 | 286 | |
dc288520 | 287 | Please refer to the source for more documentation. |
dac24ab3 | 288 | |
dc288520 HMH |
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 | |
dac24ab3 | 298 | |
dc288520 HMH |
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. | |
dac24ab3 ID |
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 | |
dc288520 HMH |
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 | ||
dac24ab3 ID |
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 | |
dc288520 HMH |
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. |