diff options
author | Dmitry Torokhov <dmitry.torokhov@gmail.com> | 2008-07-21 00:55:14 -0400 |
---|---|---|
committer | Dmitry Torokhov <dmitry.torokhov@gmail.com> | 2008-07-21 00:55:14 -0400 |
commit | 908cf4b925e419bc74f3297b2f0e51d6f8a81da2 (patch) | |
tree | 6c2da79366d4695a9c2560ab18259eca8a2a25b4 /Documentation/rfkill.txt | |
parent | 92c49890922d54cba4b1eadeb0b185773c2c9570 (diff) | |
parent | 14b395e35d1afdd8019d11b92e28041fad591b71 (diff) |
Merge master.kernel.org:/pub/scm/linux/kernel/git/torvalds/linux-2.6 into next
Diffstat (limited to 'Documentation/rfkill.txt')
-rw-r--r-- | Documentation/rfkill.txt | 547 |
1 files changed, 493 insertions, 54 deletions
diff --git a/Documentation/rfkill.txt b/Documentation/rfkill.txt index a83ff23cd68c..0843ed0163a5 100644 --- a/Documentation/rfkill.txt +++ b/Documentation/rfkill.txt | |||
@@ -1,89 +1,528 @@ | |||
1 | rfkill - RF switch subsystem support | 1 | rfkill - RF switch subsystem support |
2 | ==================================== | 2 | ==================================== |
3 | 3 | ||
4 | 1 Implementation details | 4 | 1 Introduction |
5 | 2 Driver support | 5 | 2 Implementation details |
6 | 3 Userspace support | 6 | 3 Kernel driver guidelines |
7 | 3.1 wireless device drivers | ||
8 | 3.2 platform/switch drivers | ||
9 | 3.3 input device drivers | ||
10 | 4 Kernel API | ||
11 | 5 Userspace support | ||
7 | 12 | ||
8 | =============================================================================== | ||
9 | 1: Implementation details | ||
10 | 13 | ||
11 | The rfkill switch subsystem offers support for keys often found on laptops | 14 | 1. Introduction: |
12 | to enable wireless devices like WiFi and Bluetooth. | 15 | |
16 | The rfkill switch subsystem exists to add a generic interface to circuitry that | ||
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. | ||
13 | 19 | ||
14 | This is done by providing the user 3 possibilities: | 20 | Note that disabling the signal output means that the the transmitter is to be |
15 | 1 - The rfkill system handles all events; userspace is not aware of events. | 21 | made to not emit any energy when "blocked". rfkill is not about blocking data |
16 | 2 - The rfkill system handles all events; userspace is informed about the events. | 22 | transmissions, it is about blocking energy emission. |
17 | 3 - The rfkill system does not handle events; userspace handles all events. | ||
18 | 23 | ||
19 | The buttons to enable and disable the wireless radios are important in | 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. | ||
28 | |||
29 | The buttons to enable and disable the wireless transmitters are important in | ||
20 | situations where the user is for example using his laptop on a location where | 30 | situations where the user is for example using his laptop on a location where |
21 | wireless radios _must_ be disabled (e.g. airplanes). | 31 | radio-frequency transmitters _must_ be disabled (e.g. airplanes). |
22 | Because of this requirement, userspace support for the keys should not be | 32 | |
23 | made mandatory. Because userspace might want to perform some additional smarter | 33 | Because of this requirement, userspace support for the keys should not be made |
24 | tasks when the key is pressed, rfkill still provides userspace the possibility | 34 | mandatory. Because userspace might want to perform some additional smarter |
25 | to take over the task to handle the key events. | 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 | |||
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 | |||
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. | ||
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". | ||
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 | ||
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. | ||
66 | |||
67 | The rfkill-input module also provides EPO (emergency power-off) functionality | ||
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: | ||
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. | ||
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. | ||
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 | ||
144 | on input events is broken, as there is no guarantee that an input event | ||
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 | ||
149 | register themselves with the input layer. Doing otherwise is a common | ||
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 | ||
169 | EVER LISTEN TO, OR ACT ON RFKILL INPUT EVENTS. Doing otherwise is | ||
170 | a layering violation. | ||
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 | ||
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 | |||
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 | ||
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. | ||
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 | |||
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 | |||
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 | ||
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 | ||
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. | ||
231 | |||
232 | A driver should register a device with the rfkill class when ALL of the | ||
233 | following conditions are met (they define a rfkill controller): | ||
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 | |||
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 | |||
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. | ||
26 | 258 | ||
27 | The system inside the kernel has been split into 2 separate sections: | 259 | Please refer to the corner cases and examples section for more details. |
28 | 1 - RFKILL | ||
29 | 2 - RFKILL_INPUT | ||
30 | 260 | ||
31 | The first option enables rfkill support and will make sure userspace will | 261 | When in doubt, do not issue input events. For drivers that should generate |
32 | be notified of any events through the input device. It also creates several | 262 | input events in some platforms, but not in others (e.g. b43), the best solution |
33 | sysfs entries which can be used by userspace. See section "Userspace support". | 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. | ||
34 | 267 | ||
35 | The second option provides an rfkill input handler. This handler will | ||
36 | listen to all rfkill key events and will toggle the radio accordingly. | ||
37 | With this option enabled userspace could either do nothing or simply | ||
38 | perform monitoring tasks. | ||
39 | 268 | ||
269 | Corner cases and examples: | ||
40 | ==================================== | 270 | ==================================== |
41 | 2: Driver support | ||
42 | 271 | ||
43 | To build a driver with rfkill subsystem support, the driver should | 272 | 1. If the device is an input device that, because of hardware or firmware, |
44 | depend on the Kconfig symbol RFKILL; it should _not_ depend on | 273 | causes wireless transmitters to be blocked regardless of the kernel's will, it |
45 | RKFILL_INPUT. | 274 | is still just an input device, and NOT to be registered with the rfkill class. |
46 | 275 | ||
47 | Unless key events trigger an interrupt to which the driver listens, polling | 276 | 2. If the wireless transmitter switch control is read-only, it is an input |
48 | will be required to determine the key state changes. For this the input | 277 | device and not to be registered with the rfkill class (and maybe not to be made |
49 | layer providers the input-polldev handler. | 278 | an input layer event source either, see below). |
50 | 279 | ||
51 | A driver should implement a few steps to correctly make use of the | 280 | 3. If there is some other device driver *closer* to the actual hardware the |
52 | rfkill subsystem. First for non-polling drivers: | 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. | ||
53 | 283 | ||
54 | - rfkill_allocate() | 284 | E.g: |
55 | - input_allocate_device() | 285 | [RFKILL slider switch] -- [GPIO hardware] -- [WLAN card rf-kill input] |
56 | - rfkill_register() | 286 | (platform driver) (wireless card driver) |
57 | - input_register_device() | 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 | |||
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). | ||
339 | |||
340 | |||
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 | |||
366 | Example of a WLAN wireless driver connected to the rfkill subsystem: | ||
367 | -------------------------------------------------------------------- | ||
368 | |||
369 | A certain WLAN card has one input pin that causes it to block the transmitter | ||
370 | and makes the status of that input pin available (only for reading!) to the | ||
371 | kernel driver. This is a hard rfkill input line (it cannot be overridden by | ||
372 | the kernel driver). | ||
373 | |||
374 | The card also has one PCI register that, if manipulated by the driver, causes | ||
375 | it to block the transmitter. This is a soft rfkill input line. | ||
376 | |||
377 | It has also a thermal protection circuitry that shuts down its transmitter if | ||
378 | the card overheats, and makes the status of that protection available (only for | ||
379 | reading!) to the kernel driver. This is also a hard rfkill input line. | ||
380 | |||
381 | If either one of these rfkill lines are active, the transmitter is blocked by | ||
382 | the hardware and forced offline. | ||
383 | |||
384 | The driver should allocate and attach to its struct device *ONE* instance of | ||
385 | the rfkill class (there is only one transmitter). | ||
386 | |||
387 | It can implement the get_state() hook, and return RFKILL_STATE_HARD_BLOCKED if | ||
388 | either one of its two hard rfkill input lines are active. If the two hard | ||
389 | rfkill lines are inactive, it must return RFKILL_STATE_SOFT_BLOCKED if its soft | ||
390 | rfkill input line is active. Only if none of the rfkill input lines are | ||
391 | active, will it return RFKILL_STATE_UNBLOCKED. | ||
58 | 392 | ||
59 | For polling drivers: | 393 | If it doesn't implement the get_state() hook, it must make sure that its calls |
394 | to rfkill_force_state() are enough to keep the status always up-to-date, and it | ||
395 | must do a rfkill_force_state() on resume from sleep. | ||
60 | 396 | ||
397 | Every time the driver gets a notification from the card that one of its rfkill | ||
398 | lines changed state (polling might be needed on badly designed cards that don't | ||
399 | generate interrupts for such events), it recomputes the rfkill state as per | ||
400 | above, and calls rfkill_force_state() to update it. | ||
401 | |||
402 | The driver should implement the toggle_radio() hook, that: | ||
403 | |||
404 | 1. Returns an error if one of the hardware rfkill lines are active, and the | ||
405 | caller asked for RFKILL_STATE_UNBLOCKED. | ||
406 | |||
407 | 2. Activates the soft rfkill line if the caller asked for state | ||
408 | RFKILL_STATE_SOFT_BLOCKED. It should do this even if one of the hard rfkill | ||
409 | lines are active, effectively double-blocking the transmitter. | ||
410 | |||
411 | 3. Deactivates the soft rfkill line if none of the hardware rfkill lines are | ||
412 | active and the caller asked for RFKILL_STATE_UNBLOCKED. | ||
413 | |||
414 | =============================================================================== | ||
415 | 4: Kernel API | ||
416 | |||
417 | To build a driver with rfkill subsystem support, the driver should depend on | ||
418 | (or select) the Kconfig symbol RFKILL; it should _not_ depend on RKFILL_INPUT. | ||
419 | |||
420 | The hardware the driver talks to may be write-only (where the current state | ||
421 | of the hardware is unknown), or read-write (where the hardware can be queried | ||
422 | about its current state). | ||
423 | |||
424 | The rfkill class will call the get_state hook of a device every time it needs | ||
425 | to know the *real* current state of the hardware. This can happen often. | ||
426 | |||
427 | Some hardware provides events when its status changes. In these cases, it is | ||
428 | best for the driver to not provide a get_state hook, and instead register the | ||
429 | rfkill class *already* with the correct status, and keep it updated using | ||
430 | rfkill_force_state() when it gets an event from the hardware. | ||
431 | |||
432 | There is no provision for a statically-allocated rfkill struct. You must | ||
433 | use rfkill_allocate() to allocate one. | ||
434 | |||
435 | You should: | ||
61 | - rfkill_allocate() | 436 | - rfkill_allocate() |
62 | - input_allocate_polled_device() | 437 | - modify rfkill fields (flags, name) |
438 | - modify state to the current hardware state (THIS IS THE ONLY TIME | ||
439 | YOU CAN ACCESS state DIRECTLY) | ||
63 | - rfkill_register() | 440 | - rfkill_register() |
64 | - input_register_polled_device() | ||
65 | 441 | ||
66 | When a key event has been detected, the correct event should be | 442 | The only way to set a device to the RFKILL_STATE_HARD_BLOCKED state is through |
67 | sent over the input device which has been registered by the driver. | 443 | a suitable return of get_state() or through rfkill_force_state(). |
68 | 444 | ||
69 | ==================================== | 445 | When a device is in the RFKILL_STATE_HARD_BLOCKED state, the only way to switch |
70 | 3: Userspace support | 446 | it to a different state is through a suitable return of get_state() or through |
447 | rfkill_force_state(). | ||
448 | |||
449 | If toggle_radio() is called to set a device to state RFKILL_STATE_SOFT_BLOCKED | ||
450 | when that device is already at the RFKILL_STATE_HARD_BLOCKED state, it should | ||
451 | not return an error. Instead, it should try to double-block the transmitter, | ||
452 | so that its state will change from RFKILL_STATE_HARD_BLOCKED to | ||
453 | RFKILL_STATE_SOFT_BLOCKED should the hardware blocking cease. | ||
71 | 454 | ||
72 | For each key an input device will be created which will send out the correct | 455 | Please refer to the source for more documentation. |
73 | key event when the rfkill key has been pressed. | 456 | |
457 | =============================================================================== | ||
458 | 5: Userspace support | ||
459 | |||
460 | rfkill devices issue uevents (with an action of "change"), with the following | ||
461 | environment variables set: | ||
462 | |||
463 | RFKILL_NAME | ||
464 | RFKILL_STATE | ||
465 | RFKILL_TYPE | ||
466 | |||
467 | The ABI for these variables is defined by the sysfs attributes. It is best | ||
468 | to take a quick look at the source to make sure of the possible values. | ||
469 | |||
470 | It is expected that HAL will trap those, and bridge them to DBUS, etc. These | ||
471 | events CAN and SHOULD be used to give feedback to the user about the rfkill | ||
472 | status of the system. | ||
473 | |||
474 | Input devices may issue events that are related to rfkill. These are the | ||
475 | various KEY_* events and SW_* events supported by rfkill-input.c. | ||
476 | |||
477 | ******IMPORTANT****** | ||
478 | When rfkill-input is ACTIVE, userspace is NOT TO CHANGE THE STATE OF AN RFKILL | ||
479 | SWITCH IN RESPONSE TO AN INPUT EVENT also handled by rfkill-input, unless it | ||
480 | has set to true the user_claim attribute for that particular switch. This rule | ||
481 | is *absolute*; do NOT violate it. | ||
482 | ******IMPORTANT****** | ||
483 | |||
484 | Userspace must not assume it is the only source of control for rfkill switches. | ||
485 | Their state CAN and WILL change due to firmware actions, direct user actions, | ||
486 | and the rfkill-input EPO override for *_RFKILL_ALL. | ||
487 | |||
488 | When rfkill-input is not active, userspace must initiate a rfkill status | ||
489 | change by writing to the "state" attribute in order for anything to happen. | ||
490 | |||
491 | Take particular care to implement EV_SW SW_RFKILL_ALL properly. When that | ||
492 | switch is set to OFF, *every* rfkill device *MUST* be immediately put into the | ||
493 | RFKILL_STATE_SOFT_BLOCKED state, no questions asked. | ||
74 | 494 | ||
75 | The following sysfs entries will be created: | 495 | The following sysfs entries will be created: |
76 | 496 | ||
77 | name: Name assigned by driver to this key (interface or driver name). | 497 | name: Name assigned by driver to this key (interface or driver name). |
78 | type: Name of the key type ("wlan", "bluetooth", etc). | 498 | type: Name of the key type ("wlan", "bluetooth", etc). |
79 | state: Current state of the key. 1: On, 0: Off. | 499 | state: Current state of the transmitter |
500 | 0: RFKILL_STATE_SOFT_BLOCKED | ||
501 | transmitter is forced off, but one can override it | ||
502 | by a write to the state attribute; | ||
503 | 1: RFKILL_STATE_UNBLOCKED | ||
504 | transmiter is NOT forced off, and may operate if | ||
505 | all other conditions for such operation are met | ||
506 | (such as interface is up and configured, etc); | ||
507 | 2: RFKILL_STATE_HARD_BLOCKED | ||
508 | transmitter is forced off by something outside of | ||
509 | the driver's control. One cannot set a device to | ||
510 | this state through writes to the state attribute; | ||
80 | claim: 1: Userspace handles events, 0: Kernel handles events | 511 | claim: 1: Userspace handles events, 0: Kernel handles events |
81 | 512 | ||
82 | Both the "state" and "claim" entries are also writable. For the "state" entry | 513 | Both the "state" and "claim" entries are also writable. For the "state" entry |
83 | this means that when 1 or 0 is written all radios, not yet in the requested | 514 | this means that when 1 or 0 is written, the device rfkill state (if not yet in |
84 | state, will be will be toggled accordingly. | 515 | the requested state), will be will be toggled accordingly. |
516 | |||
85 | For the "claim" entry writing 1 to it means that the kernel no longer handles | 517 | For the "claim" entry writing 1 to it means that the kernel no longer handles |
86 | key events even though RFKILL_INPUT input was enabled. When "claim" has been | 518 | key events even though RFKILL_INPUT input was enabled. When "claim" has been |
87 | set to 0, userspace should make sure that it listens for the input events or | 519 | set to 0, userspace should make sure that it listens for the input events or |
88 | check the sysfs "state" entry regularly to correctly perform the required | 520 | check the sysfs "state" entry regularly to correctly perform the required tasks |
89 | tasks when the rkfill key is pressed. | 521 | when the rkfill key is pressed. |
522 | |||
523 | A note about input devices and EV_SW events: | ||
524 | |||
525 | In order to know the current state of an input device switch (like | ||
526 | SW_RFKILL_ALL), you will need to use an IOCTL. That information is not | ||
527 | available through sysfs in a generic way at this time, and it is not available | ||
528 | through the rfkill class AT ALL. | ||