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