]>
Commit | Line | Data |
---|---|---|
dac24ab3 ID |
1 | rfkill - RF switch subsystem support |
2 | ==================================== | |
3 | ||
4 | 1 Implementation details | |
5 | 2 Driver support | |
6 | 3 Userspace support | |
7 | ||
8 | =============================================================================== | |
9 | 1: Implementation details | |
10 | ||
f3146aff HMH |
11 | The rfkill switch subsystem exists to add a generic interface to circuitry that |
12 | can enable or disable the RF output of a radio *transmitter* of any type. | |
13 | ||
14 | When a rfkill switch is in the RFKILL_STATE_ON, the radio transmitter is | |
15 | *enabled*. When the rfkill switch is in the RFKILL_STATE_OFF, the radio | |
16 | transmitter is *disabled*. | |
17 | ||
dac24ab3 ID |
18 | The rfkill switch subsystem offers support for keys often found on laptops |
19 | to enable wireless devices like WiFi and Bluetooth. | |
20 | ||
21 | This is done by providing the user 3 possibilities: | |
22 | 1 - The rfkill system handles all events; userspace is not aware of events. | |
23 | 2 - The rfkill system handles all events; userspace is informed about the events. | |
24 | 3 - The rfkill system does not handle events; userspace handles all events. | |
25 | ||
26 | The buttons to enable and disable the wireless radios are important in | |
27 | situations where the user is for example using his laptop on a location where | |
28 | wireless radios _must_ be disabled (e.g. airplanes). | |
29 | Because of this requirement, userspace support for the keys should not be | |
30 | made mandatory. Because userspace might want to perform some additional smarter | |
31 | tasks when the key is pressed, rfkill still provides userspace the possibility | |
32 | to take over the task to handle the key events. | |
33 | ||
34 | The system inside the kernel has been split into 2 separate sections: | |
35 | 1 - RFKILL | |
36 | 2 - RFKILL_INPUT | |
37 | ||
38 | The first option enables rfkill support and will make sure userspace will | |
39 | be notified of any events through the input device. It also creates several | |
40 | sysfs entries which can be used by userspace. See section "Userspace support". | |
41 | ||
42 | The second option provides an rfkill input handler. This handler will | |
43 | listen to all rfkill key events and will toggle the radio accordingly. | |
44 | With this option enabled userspace could either do nothing or simply | |
45 | perform monitoring tasks. | |
46 | ||
47 | ==================================== | |
48 | 2: Driver support | |
49 | ||
50 | To build a driver with rfkill subsystem support, the driver should | |
51 | depend on the Kconfig symbol RFKILL; it should _not_ depend on | |
52 | RKFILL_INPUT. | |
53 | ||
54 | Unless key events trigger an interrupt to which the driver listens, polling | |
55 | will be required to determine the key state changes. For this the input | |
56 | layer providers the input-polldev handler. | |
57 | ||
58 | A driver should implement a few steps to correctly make use of the | |
59 | rfkill subsystem. First for non-polling drivers: | |
60 | ||
61 | - rfkill_allocate() | |
62 | - input_allocate_device() | |
63 | - rfkill_register() | |
64 | - input_register_device() | |
65 | ||
66 | For polling drivers: | |
67 | ||
68 | - rfkill_allocate() | |
69 | - input_allocate_polled_device() | |
70 | - rfkill_register() | |
71 | - input_register_polled_device() | |
72 | ||
73 | When a key event has been detected, the correct event should be | |
74 | sent over the input device which has been registered by the driver. | |
75 | ||
76 | ==================================== | |
77 | 3: Userspace support | |
78 | ||
79 | For each key an input device will be created which will send out the correct | |
80 | key event when the rfkill key has been pressed. | |
81 | ||
82 | The following sysfs entries will be created: | |
83 | ||
84 | name: Name assigned by driver to this key (interface or driver name). | |
85 | type: Name of the key type ("wlan", "bluetooth", etc). | |
86 | state: Current state of the key. 1: On, 0: Off. | |
87 | claim: 1: Userspace handles events, 0: Kernel handles events | |
88 | ||
89 | Both the "state" and "claim" entries are also writable. For the "state" entry | |
90 | this means that when 1 or 0 is written all radios, not yet in the requested | |
91 | state, will be will be toggled accordingly. | |
92 | For the "claim" entry writing 1 to it means that the kernel no longer handles | |
93 | key events even though RFKILL_INPUT input was enabled. When "claim" has been | |
94 | set to 0, userspace should make sure that it listens for the input events or | |
95 | check the sysfs "state" entry regularly to correctly perform the required | |
96 | tasks when the rkfill key is pressed. |