]>
Commit | Line | Data |
---|---|---|
1 | rfkill - RF kill switch support | |
2 | =============================== | |
3 | ||
4 | 1. Introduction | |
5 | 2. Implementation details | |
6 | 3. Kernel API | |
7 | 4. Userspace support | |
8 | ||
9 | ||
10 | 1. Introduction | |
11 | ||
12 | The rfkill subsystem provides a generic interface to disabling any radio | |
13 | transmitter in the system. When a transmitter is blocked, it shall not | |
14 | radiate any power. | |
15 | ||
16 | The subsystem also provides the ability to react on button presses and | |
17 | disable all transmitters of a certain type (or all). This is intended for | |
18 | situations where transmitters need to be turned off, for example on | |
19 | aircraft. | |
20 | ||
21 | The rfkill subsystem has a concept of "hard" and "soft" block, which | |
22 | differ little in their meaning (block == transmitters off) but rather in | |
23 | whether they can be changed or not: | |
24 | - hard block: read-only radio block that cannot be overridden by software | |
25 | - soft block: writable radio block (need not be readable) that is set by | |
26 | the system software. | |
27 | ||
28 | The rfkill subsystem has two parameters, rfkill.default_state and | |
29 | rfkill.master_switch_mode, which are documented in kernel-parameters.txt. | |
30 | ||
31 | ||
32 | 2. Implementation details | |
33 | ||
34 | The rfkill subsystem is composed of three main components: | |
35 | * the rfkill core, | |
36 | * the deprecated rfkill-input module (an input layer handler, being | |
37 | replaced by userspace policy code) and | |
38 | * the rfkill drivers. | |
39 | ||
40 | The rfkill core provides API for kernel drivers to register their radio | |
41 | transmitter with the kernel, methods for turning it on and off and, letting | |
42 | the system know about hardware-disabled states that may be implemented on | |
43 | the device. | |
44 | ||
45 | The rfkill core code also notifies userspace of state changes, and provides | |
46 | ways for userspace to query the current states. See the "Userspace support" | |
47 | section below. | |
48 | ||
49 | When the device is hard-blocked (either by a call to rfkill_set_hw_state() | |
50 | or from query_hw_block) set_block() will be invoked for additional software | |
51 | block, but drivers can ignore the method call since they can use the return | |
52 | value of the function rfkill_set_hw_state() to sync the software state | |
53 | instead of keeping track of calls to set_block(). In fact, drivers should | |
54 | use the return value of rfkill_set_hw_state() unless the hardware actually | |
55 | keeps track of soft and hard block separately. | |
56 | ||
57 | ||
58 | 3. Kernel API | |
59 | ||
60 | ||
61 | Drivers for radio transmitters normally implement an rfkill driver. | |
62 | ||
63 | Platform drivers might implement input devices if the rfkill button is just | |
64 | that, a button. If that button influences the hardware then you need to | |
65 | implement an rfkill driver instead. This also applies if the platform provides | |
66 | a way to turn on/off the transmitter(s). | |
67 | ||
68 | For some platforms, it is possible that the hardware state changes during | |
69 | suspend/hibernation, in which case it will be necessary to update the rfkill | |
70 | core with the current state is at resume time. | |
71 | ||
72 | To create an rfkill driver, driver's Kconfig needs to have | |
73 | ||
74 | depends on RFKILL || !RFKILL | |
75 | ||
76 | to ensure the driver cannot be built-in when rfkill is modular. The !RFKILL | |
77 | case allows the driver to be built when rfkill is not configured, which | |
78 | case all rfkill API can still be used but will be provided by static inlines | |
79 | which compile to almost nothing. | |
80 | ||
81 | Calling rfkill_set_hw_state() when a state change happens is required from | |
82 | rfkill drivers that control devices that can be hard-blocked unless they also | |
83 | assign the poll_hw_block() callback (then the rfkill core will poll the | |
84 | device). Don't do this unless you cannot get the event in any other way. | |
85 | ||
86 | ||
87 | ||
88 | 5. Userspace support | |
89 | ||
90 | The recommended userspace interface to use is /dev/rfkill, which is a misc | |
91 | character device that allows userspace to obtain and set the state of rfkill | |
92 | devices and sets of devices. It also notifies userspace about device addition | |
93 | and removal. The API is a simple read/write API that is defined in | |
94 | linux/rfkill.h, with one ioctl that allows turning off the deprecated input | |
95 | handler in the kernel for the transition period. | |
96 | ||
97 | Except for the one ioctl, communication with the kernel is done via read() | |
98 | and write() of instances of 'struct rfkill_event'. In this structure, the | |
99 | soft and hard block are properly separated (unlike sysfs, see below) and | |
100 | userspace is able to get a consistent snapshot of all rfkill devices in the | |
101 | system. Also, it is possible to switch all rfkill drivers (or all drivers of | |
102 | a specified type) into a state which also updates the default state for | |
103 | hotplugged devices. | |
104 | ||
105 | After an application opens /dev/rfkill, it can read the current state of all | |
106 | devices. Changes can be either obtained by either polling the descriptor for | |
107 | hotplug or state change events or by listening for uevents emitted by the | |
108 | rfkill core framework. | |
109 | ||
110 | Additionally, each rfkill device is registered in sysfs and emits uevents. | |
111 | ||
112 | rfkill devices issue uevents (with an action of "change"), with the following | |
113 | environment variables set: | |
114 | ||
115 | RFKILL_NAME | |
116 | RFKILL_STATE | |
117 | RFKILL_TYPE | |
118 | ||
119 | The contents of these variables corresponds to the "name", "state" and | |
120 | "type" sysfs files explained above. | |
121 | ||
122 | ||
123 | For further details consult Documentation/ABI/stable/sysfs-class-rfkill. |