]>
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 | |
f7983f73 HMH |
7 | 3.1 wireless device drivers |
8 | 3.2 platform/switch drivers | |
9 | 3.3 input device drivers | |
dc288520 HMH |
10 | 4 Kernel API |
11 | 5 Userspace support | |
dac24ab3 | 12 | |
dc288520 HMH |
13 | |
14 | 1. Introduction: | |
dac24ab3 | 15 | |
f3146aff | 16 | The rfkill switch subsystem exists to add a generic interface to circuitry that |
dc288520 HMH |
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. | |
f3146aff | 19 | |
f7983f73 HMH |
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. | |
f3146aff | 28 | |
dc288520 HMH |
29 | The buttons to enable and disable the wireless transmitters are important in |
30 | situations where the user is for example using his laptop on a location where | |
31 | radio-frequency transmitters _must_ be disabled (e.g. airplanes). | |
dac24ab3 | 32 | |
dc288520 HMH |
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. | |
dac24ab3 | 37 | |
dc288520 HMH |
38 | =============================================================================== |
39 | 2: Implementation details | |
40 | ||
f7983f73 HMH |
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 | ||
dc288520 HMH |
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. | |
f7983f73 HMH |
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". | |
dc288520 HMH |
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 | |
f7983f73 HMH |
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. | |
dc288520 HMH |
66 | |
67 | The rfkill-input module also provides EPO (emergency power-off) functionality | |
f7983f73 HMH |
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. | |
70 | ||
71 | ||
72 | Important terms for the rfkill subsystem: | |
73 | ||
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): | |
78 | ||
79 | rfkill switch: | |
80 | ||
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: | |
dc288520 | 86 | |
f7983f73 HMH |
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). | |
dac24ab3 | 90 | |
f7983f73 | 91 | rfkill line: |
dac24ab3 | 92 | |
f7983f73 HMH |
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). | |
dc288520 | 97 | |
f7983f73 | 98 | soft rfkill line/software rfkill line: |
dc288520 | 99 | |
f7983f73 HMH |
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. | |
5005657c HMH |
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. | |
dc288520 HMH |
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 | |
f7983f73 | 144 | on input events is broken, as there is no guarantee that an input event |
dc288520 HMH |
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 | |
f7983f73 | 149 | register themselves with the input layer. Doing otherwise is a common |
dc288520 HMH |
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 | |
f7983f73 HMH |
169 | EVER LISTEN TO, OR ACT ON RFKILL INPUT EVENTS. Doing otherwise is |
170 | a layering violation. | |
dc288520 HMH |
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 | |
f7983f73 HMH |
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 | ||
dc288520 HMH |
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 | |
5005657c HMH |
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. | |
dc288520 HMH |
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 | ||
f7983f73 HMH |
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. | |
219 | ||
dc288520 | 220 | The first thing one needs to know is whether his driver should be talking to |
f7983f73 HMH |
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. | |
dc288520 | 224 | |
f7983f73 | 225 | Do not mistake input devices for rfkill controllers. The only type of "rfkill |
dc288520 HMH |
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 | |
f7983f73 HMH |
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. | |
dc288520 HMH |
231 | |
232 | A driver should register a device with the rfkill class when ALL of the | |
f7983f73 | 233 | following conditions are met (they define a rfkill controller): |
dc288520 HMH |
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 | ||
f7983f73 HMH |
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 | ||
dc288520 HMH |
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 | ||
f7983f73 | 259 | Please refer to the corner cases and examples section for more details. |
dac24ab3 | 260 | |
dc288520 HMH |
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. | |
dac24ab3 | 267 | |
dc288520 HMH |
268 | |
269 | Corner cases and examples: | |
dac24ab3 | 270 | ==================================== |
dac24ab3 | 271 | |
dc288520 HMH |
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. | |
dac24ab3 | 275 | |
dc288520 HMH |
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). | |
dac24ab3 | 279 | |
dc288520 HMH |
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. | |
dac24ab3 | 283 | |
dc288520 HMH |
284 | E.g: |
285 | [RFKILL slider switch] -- [GPIO hardware] -- [WLAN card rf-kill input] | |
286 | (platform driver) (wireless card driver) | |
287 | ||
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)... | |
293 | ||
294 | On the other hand, some embedded devices do this: | |
295 | ||
296 | [RFKILL slider switch] -- [WLAN card rf-kill input] | |
297 | (wireless card driver) | |
298 | ||
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: | |
307 | ==================================== | |
308 | ||
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 | ||
f7983f73 HMH |
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 :-) | |
329 | ||
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). | |
dc288520 | 339 | |
dc288520 | 340 | |
f7983f73 HMH |
341 | 3.1 Guidelines for wireless device drivers |
342 | ------------------------------------------ | |
343 | ||
344 | 1. Each independent transmitter in a wireless device (usually there is only one | |
345 | transmitter per device) should have a SINGLE rfkill class attached to it. | |
346 | ||
347 | 2. If the device does not have any sort of hardware assistance to allow the | |
348 | driver to rfkill the device, the driver should emulate it by taking all actions | |
349 | required to silence the transmitter. | |
350 | ||
351 | 3. If it is impossible to silence the transmitter (i.e. it still emits energy, | |
352 | even if it is just in brief pulses, when there is no data to transmit and there | |
353 | is no hardware support to turn it off) do NOT lie to the users. Do not attach | |
354 | it to a rfkill class. The rfkill subsystem does not deal with data | |
355 | transmission, it deals with energy emission. If the transmitter is emitting | |
356 | energy, it is not blocked in rfkill terms. | |
357 | ||
358 | 4. It doesn't matter if the device has multiple rfkill input lines affecting | |
359 | the same transmitter, their combined state is to be exported as a single state | |
360 | per transmitter (see rule 1). | |
361 | ||
362 | This rule exists because users of the rfkill subsystem expect to get (and set, | |
363 | when possible) the overall transmitter rfkill state, not of a particular rfkill | |
364 | line. | |
365 | ||
e10e0dfe HMH |
366 | 5. During suspend, the rfkill class will attempt to soft-block the radio |
367 | through a call to rfkill->toggle_radio, and will try to restore its previous | |
368 | state during resume. After a rfkill class is suspended, it will *not* call | |
369 | rfkill->toggle_radio until it is resumed. | |
370 | ||
f7983f73 HMH |
371 | Example of a WLAN wireless driver connected to the rfkill subsystem: |
372 | -------------------------------------------------------------------- | |
373 | ||
374 | A certain WLAN card has one input pin that causes it to block the transmitter | |
375 | and makes the status of that input pin available (only for reading!) to the | |
376 | kernel driver. This is a hard rfkill input line (it cannot be overridden by | |
377 | the kernel driver). | |
378 | ||
379 | The card also has one PCI register that, if manipulated by the driver, causes | |
380 | it to block the transmitter. This is a soft rfkill input line. | |
381 | ||
382 | It has also a thermal protection circuitry that shuts down its transmitter if | |
383 | the card overheats, and makes the status of that protection available (only for | |
384 | reading!) to the kernel driver. This is also a hard rfkill input line. | |
385 | ||
386 | If either one of these rfkill lines are active, the transmitter is blocked by | |
387 | the hardware and forced offline. | |
388 | ||
389 | The driver should allocate and attach to its struct device *ONE* instance of | |
390 | the rfkill class (there is only one transmitter). | |
391 | ||
392 | It can implement the get_state() hook, and return RFKILL_STATE_HARD_BLOCKED if | |
393 | either one of its two hard rfkill input lines are active. If the two hard | |
394 | rfkill lines are inactive, it must return RFKILL_STATE_SOFT_BLOCKED if its soft | |
395 | rfkill input line is active. Only if none of the rfkill input lines are | |
396 | active, will it return RFKILL_STATE_UNBLOCKED. | |
397 | ||
2fd9b221 HMH |
398 | Since the device has a hardware rfkill line, it IS subject to state changes |
399 | external to rfkill. Therefore, the driver must make sure that it calls | |
400 | rfkill_force_state() to keep the status always up-to-date, and it must do a | |
401 | rfkill_force_state() on resume from sleep. | |
f7983f73 HMH |
402 | |
403 | Every time the driver gets a notification from the card that one of its rfkill | |
404 | lines changed state (polling might be needed on badly designed cards that don't | |
405 | generate interrupts for such events), it recomputes the rfkill state as per | |
406 | above, and calls rfkill_force_state() to update it. | |
407 | ||
408 | The driver should implement the toggle_radio() hook, that: | |
409 | ||
410 | 1. Returns an error if one of the hardware rfkill lines are active, and the | |
411 | caller asked for RFKILL_STATE_UNBLOCKED. | |
412 | ||
413 | 2. Activates the soft rfkill line if the caller asked for state | |
414 | RFKILL_STATE_SOFT_BLOCKED. It should do this even if one of the hard rfkill | |
415 | lines are active, effectively double-blocking the transmitter. | |
416 | ||
417 | 3. Deactivates the soft rfkill line if none of the hardware rfkill lines are | |
418 | active and the caller asked for RFKILL_STATE_UNBLOCKED. | |
dc288520 HMH |
419 | |
420 | =============================================================================== | |
421 | 4: Kernel API | |
422 | ||
423 | To build a driver with rfkill subsystem support, the driver should depend on | |
f7983f73 | 424 | (or select) the Kconfig symbol RFKILL; it should _not_ depend on RKFILL_INPUT. |
dc288520 HMH |
425 | |
426 | The hardware the driver talks to may be write-only (where the current state | |
427 | of the hardware is unknown), or read-write (where the hardware can be queried | |
428 | about its current state). | |
429 | ||
430 | The rfkill class will call the get_state hook of a device every time it needs | |
2fd9b221 HMH |
431 | to know the *real* current state of the hardware. This can happen often, but |
432 | it does not do any polling, so it is not enough on hardware that is subject | |
433 | to state changes outside of the rfkill subsystem. | |
434 | ||
435 | Therefore, calling rfkill_force_state() when a state change happens is | |
436 | mandatory when the device has a hardware rfkill line, or when something else | |
437 | like the firmware could cause its state to be changed without going through the | |
438 | rfkill class. | |
dc288520 HMH |
439 | |
440 | Some hardware provides events when its status changes. In these cases, it is | |
441 | best for the driver to not provide a get_state hook, and instead register the | |
442 | rfkill class *already* with the correct status, and keep it updated using | |
443 | rfkill_force_state() when it gets an event from the hardware. | |
dac24ab3 | 444 | |
2fd9b221 HMH |
445 | rfkill_force_state() must be used on the device resume handlers to update the |
446 | rfkill status, should there be any chance of the device status changing during | |
447 | the sleep. | |
448 | ||
dc288520 HMH |
449 | There is no provision for a statically-allocated rfkill struct. You must |
450 | use rfkill_allocate() to allocate one. | |
dac24ab3 | 451 | |
dc288520 | 452 | You should: |
dac24ab3 | 453 | - rfkill_allocate() |
dc288520 HMH |
454 | - modify rfkill fields (flags, name) |
455 | - modify state to the current hardware state (THIS IS THE ONLY TIME | |
456 | YOU CAN ACCESS state DIRECTLY) | |
dac24ab3 | 457 | - rfkill_register() |
dac24ab3 | 458 | |
5005657c HMH |
459 | The only way to set a device to the RFKILL_STATE_HARD_BLOCKED state is through |
460 | a suitable return of get_state() or through rfkill_force_state(). | |
461 | ||
462 | When a device is in the RFKILL_STATE_HARD_BLOCKED state, the only way to switch | |
463 | it to a different state is through a suitable return of get_state() or through | |
464 | rfkill_force_state(). | |
465 | ||
466 | If toggle_radio() is called to set a device to state RFKILL_STATE_SOFT_BLOCKED | |
467 | when that device is already at the RFKILL_STATE_HARD_BLOCKED state, it should | |
468 | not return an error. Instead, it should try to double-block the transmitter, | |
469 | so that its state will change from RFKILL_STATE_HARD_BLOCKED to | |
470 | RFKILL_STATE_SOFT_BLOCKED should the hardware blocking cease. | |
471 | ||
dc288520 | 472 | Please refer to the source for more documentation. |
dac24ab3 | 473 | |
dc288520 HMH |
474 | =============================================================================== |
475 | 5: Userspace support | |
476 | ||
477 | rfkill devices issue uevents (with an action of "change"), with the following | |
478 | environment variables set: | |
479 | ||
480 | RFKILL_NAME | |
481 | RFKILL_STATE | |
482 | RFKILL_TYPE | |
dac24ab3 | 483 | |
dc288520 HMH |
484 | The ABI for these variables is defined by the sysfs attributes. It is best |
485 | to take a quick look at the source to make sure of the possible values. | |
486 | ||
487 | It is expected that HAL will trap those, and bridge them to DBUS, etc. These | |
488 | events CAN and SHOULD be used to give feedback to the user about the rfkill | |
489 | status of the system. | |
490 | ||
491 | Input devices may issue events that are related to rfkill. These are the | |
492 | various KEY_* events and SW_* events supported by rfkill-input.c. | |
493 | ||
494 | ******IMPORTANT****** | |
495 | When rfkill-input is ACTIVE, userspace is NOT TO CHANGE THE STATE OF AN RFKILL | |
496 | SWITCH IN RESPONSE TO AN INPUT EVENT also handled by rfkill-input, unless it | |
497 | has set to true the user_claim attribute for that particular switch. This rule | |
498 | is *absolute*; do NOT violate it. | |
499 | ******IMPORTANT****** | |
500 | ||
501 | Userspace must not assume it is the only source of control for rfkill switches. | |
f7983f73 HMH |
502 | Their state CAN and WILL change due to firmware actions, direct user actions, |
503 | and the rfkill-input EPO override for *_RFKILL_ALL. | |
dc288520 | 504 | |
f7983f73 | 505 | When rfkill-input is not active, userspace must initiate a rfkill status |
dc288520 HMH |
506 | change by writing to the "state" attribute in order for anything to happen. |
507 | ||
508 | Take particular care to implement EV_SW SW_RFKILL_ALL properly. When that | |
509 | switch is set to OFF, *every* rfkill device *MUST* be immediately put into the | |
5005657c | 510 | RFKILL_STATE_SOFT_BLOCKED state, no questions asked. |
dac24ab3 ID |
511 | |
512 | The following sysfs entries will be created: | |
513 | ||
514 | name: Name assigned by driver to this key (interface or driver name). | |
515 | type: Name of the key type ("wlan", "bluetooth", etc). | |
5005657c HMH |
516 | state: Current state of the transmitter |
517 | 0: RFKILL_STATE_SOFT_BLOCKED | |
f7983f73 HMH |
518 | transmitter is forced off, but one can override it |
519 | by a write to the state attribute; | |
5005657c HMH |
520 | 1: RFKILL_STATE_UNBLOCKED |
521 | transmiter is NOT forced off, and may operate if | |
522 | all other conditions for such operation are met | |
f7983f73 | 523 | (such as interface is up and configured, etc); |
5005657c HMH |
524 | 2: RFKILL_STATE_HARD_BLOCKED |
525 | transmitter is forced off by something outside of | |
f7983f73 HMH |
526 | the driver's control. One cannot set a device to |
527 | this state through writes to the state attribute; | |
dac24ab3 ID |
528 | claim: 1: Userspace handles events, 0: Kernel handles events |
529 | ||
530 | Both the "state" and "claim" entries are also writable. For the "state" entry | |
dc288520 HMH |
531 | this means that when 1 or 0 is written, the device rfkill state (if not yet in |
532 | the requested state), will be will be toggled accordingly. | |
533 | ||
dac24ab3 ID |
534 | For the "claim" entry writing 1 to it means that the kernel no longer handles |
535 | key events even though RFKILL_INPUT input was enabled. When "claim" has been | |
536 | set to 0, userspace should make sure that it listens for the input events or | |
dc288520 HMH |
537 | check the sysfs "state" entry regularly to correctly perform the required tasks |
538 | when the rkfill key is pressed. | |
539 | ||
540 | A note about input devices and EV_SW events: | |
541 | ||
542 | In order to know the current state of an input device switch (like | |
543 | SW_RFKILL_ALL), you will need to use an IOCTL. That information is not | |
544 | available through sysfs in a generic way at this time, and it is not available | |
545 | through the rfkill class AT ALL. |