]>
Commit | Line | Data |
---|---|---|
19d337df JB |
1 | rfkill - RF kill switch support |
2 | =============================== | |
dac24ab3 | 3 | |
19d337df JB |
4 | 1. Introduction |
5 | 2. Implementation details | |
6 | 3. Kernel driver guidelines | |
7 | 4. Kernel API | |
8 | 5. Userspace support | |
dac24ab3 | 9 | |
dc288520 | 10 | |
19d337df | 11 | 1. Introduction |
dac24ab3 | 12 | |
19d337df JB |
13 | The rfkill subsystem provides a generic interface to disabling any radio |
14 | transmitter in the system. When a transmitter is blocked, it shall not | |
15 | radiate any power. | |
f3146aff | 16 | |
19d337df JB |
17 | The subsystem also provides the ability to react on button presses and |
18 | disable all transmitters of a certain type (or all). This is intended for | |
19 | situations where transmitters need to be turned off, for example on | |
20 | aircraft. | |
f7983f73 | 21 | |
f3146aff | 22 | |
dac24ab3 | 23 | |
19d337df | 24 | 2. Implementation details |
dc288520 | 25 | |
f7983f73 HMH |
26 | The rfkill subsystem is composed of various components: the rfkill class, the |
27 | rfkill-input module (an input layer handler), and some specific input layer | |
28 | events. | |
29 | ||
19d337df JB |
30 | The rfkill class is provided for kernel drivers to register their radio |
31 | transmitter with the kernel, provide methods for turning it on and off and, | |
32 | optionally, letting the system know about hardware-disabled states that may | |
33 | be implemented on the device. This code is enabled with the CONFIG_RFKILL | |
34 | Kconfig option, which drivers can "select". | |
f7983f73 | 35 | |
19d337df JB |
36 | The rfkill class code also notifies userspace of state changes, this is |
37 | achieved via uevents. It also provides some sysfs files for userspace to | |
38 | check the status of radio transmitters. See the "Userspace support" section | |
39 | below. | |
bed7aac9 | 40 | |
bed7aac9 | 41 | |
19d337df JB |
42 | The rfkill-input code implements a basic response to rfkill buttons -- it |
43 | implements turning on/off all devices of a certain class (or all). | |
bed7aac9 | 44 | |
19d337df JB |
45 | When the device is hard-blocked (either by a call to rfkill_set_hw_state() |
46 | or from query_hw_block) set_block() will be invoked but drivers can well | |
47 | ignore the method call since they can use the return value of the function | |
48 | rfkill_set_hw_state() to sync the software state instead of keeping track | |
49 | of calls to set_block(). | |
bed7aac9 | 50 | |
bed7aac9 | 51 | |
19d337df | 52 | The entire functionality is spread over more than one subsystem: |
bed7aac9 | 53 | |
19d337df JB |
54 | * The kernel input layer generates KEY_WWAN, KEY_WLAN etc. and |
55 | SW_RFKILL_ALL -- when the user presses a button. Drivers for radio | |
56 | transmitters generally do not register to the input layer, unless the | |
57 | device really provides an input device (i.e. a button that has no | |
58 | effect other than generating a button press event) | |
bed7aac9 | 59 | |
19d337df JB |
60 | * The rfkill-input code hooks up to these events and switches the soft-block |
61 | of the various radio transmitters, depending on the button type. | |
e10e0dfe | 62 | |
19d337df | 63 | * The rfkill drivers turn off/on their transmitters as requested. |
f7983f73 | 64 | |
19d337df JB |
65 | * The rfkill class will generate userspace notifications (uevents) to tell |
66 | userspace what the current state is. | |
f7983f73 | 67 | |
f7983f73 | 68 | |
f7983f73 | 69 | |
19d337df | 70 | 3. Kernel driver guidelines |
f7983f73 | 71 | |
f7983f73 | 72 | |
19d337df JB |
73 | Drivers for radio transmitters normally implement only the rfkill class. |
74 | These drivers may not unblock the transmitter based on own decisions, they | |
75 | should act on information provided by the rfkill class only. | |
f7983f73 | 76 | |
19d337df JB |
77 | Platform drivers might implement input devices if the rfkill button is just |
78 | that, a button. If that button influences the hardware then you need to | |
79 | implement an rfkill class instead. This also applies if the platform provides | |
80 | a way to turn on/off the transmitter(s). | |
f7983f73 | 81 | |
19d337df JB |
82 | During suspend/hibernation, transmitters should only be left enabled when |
83 | wake-on wlan or similar functionality requires it and the device wasn't | |
84 | blocked before suspend/hibernate. Note that it may be necessary to update | |
85 | the rfkill subsystem's idea of what the current state is at resume time if | |
86 | the state may have changed over suspend. | |
f7983f73 | 87 | |
f7983f73 | 88 | |
f7983f73 | 89 | |
19d337df | 90 | 4. Kernel API |
dc288520 HMH |
91 | |
92 | To build a driver with rfkill subsystem support, the driver should depend on | |
19d337df | 93 | (or select) the Kconfig symbol RFKILL. |
dc288520 HMH |
94 | |
95 | The hardware the driver talks to may be write-only (where the current state | |
96 | of the hardware is unknown), or read-write (where the hardware can be queried | |
97 | about its current state). | |
98 | ||
19d337df JB |
99 | Calling rfkill_set_hw_state() when a state change happens is required from |
100 | rfkill drivers that control devices that can be hard-blocked unless they also | |
101 | assign the poll_hw_block() callback (then the rfkill core will poll the | |
102 | device). Don't do this unless you cannot get the event in any other way. | |
dac24ab3 | 103 | |
5005657c | 104 | |
5005657c | 105 | |
19d337df | 106 | 5. Userspace support |
dac24ab3 | 107 | |
19d337df | 108 | The following sysfs entries exist for every rfkill device: |
dac24ab3 ID |
109 | |
110 | name: Name assigned by driver to this key (interface or driver name). | |
111 | type: Name of the key type ("wlan", "bluetooth", etc). | |
5005657c HMH |
112 | state: Current state of the transmitter |
113 | 0: RFKILL_STATE_SOFT_BLOCKED | |
19d337df | 114 | transmitter is turned off by software |
5005657c | 115 | 1: RFKILL_STATE_UNBLOCKED |
f71fea23 | 116 | transmitter is (potentially) active |
5005657c HMH |
117 | 2: RFKILL_STATE_HARD_BLOCKED |
118 | transmitter is forced off by something outside of | |
19d337df JB |
119 | the driver's control. |
120 | claim: 0: Kernel handles events (currently always reads that value) | |
121 | ||
122 | rfkill devices also issue uevents (with an action of "change"), with the | |
123 | following environment variables set: | |
124 | ||
125 | RFKILL_NAME | |
126 | RFKILL_STATE | |
127 | RFKILL_TYPE | |
128 | ||
129 | The contents of these variables corresponds to the "name", "state" and | |
130 | "type" sysfs files explained above. | |
f71fea23 JB |
131 | |
132 | An alternative userspace interface exists as a misc device /dev/rfkill, | |
133 | which allows userspace to obtain and set the state of rfkill devices and | |
134 | sets of devices. It also notifies userspace about device addition and | |
135 | removal. The API is a simple read/write API that is defined in | |
136 | linux/rfkill.h. |