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