aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/rfkill.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/rfkill.txt')
-rw-r--r--Documentation/rfkill.txt137
1 files changed, 69 insertions, 68 deletions
diff --git a/Documentation/rfkill.txt b/Documentation/rfkill.txt
index 1b74b5f30af4..c8acd8659e91 100644
--- a/Documentation/rfkill.txt
+++ b/Documentation/rfkill.txt
@@ -3,9 +3,8 @@ rfkill - RF kill switch support
3 3
41. Introduction 41. Introduction
52. Implementation details 52. Implementation details
63. Kernel driver guidelines 63. Kernel API
74. Kernel API 74. Userspace support
85. Userspace support
9 8
10 9
111. Introduction 101. Introduction
@@ -19,82 +18,62 @@ disable all transmitters of a certain type (or all). This is intended for
19situations where transmitters need to be turned off, for example on 18situations where transmitters need to be turned off, for example on
20aircraft. 19aircraft.
21 20
21The rfkill subsystem has a concept of "hard" and "soft" block, which
22differ little in their meaning (block == transmitters off) but rather in
23whether they can be changed or not:
24 - hard block: read-only radio block that cannot be overriden by software
25 - soft block: writable radio block (need not be readable) that is set by
26 the system software.
22 27
23 28
242. Implementation details 292. Implementation details
25 30
26The rfkill subsystem is composed of various components: the rfkill class, the 31The rfkill subsystem is composed of three main components:
27rfkill-input module (an input layer handler), and some specific input layer 32 * the rfkill core,
28events. 33 * the deprecated rfkill-input module (an input layer handler, being
29 34 replaced by userspace policy code) and
30The rfkill class is provided for kernel drivers to register their radio 35 * the rfkill drivers.
31transmitter with the kernel, provide methods for turning it on and off and,
32optionally, letting the system know about hardware-disabled states that may
33be implemented on the device. This code is enabled with the CONFIG_RFKILL
34Kconfig option, which drivers can "select".
35
36The rfkill class code also notifies userspace of state changes, this is
37achieved via uevents. It also provides some sysfs files for userspace to
38check the status of radio transmitters. See the "Userspace support" section
39below.
40 36
37The rfkill core provides API for kernel drivers to register their radio
38transmitter with the kernel, methods for turning it on and off and, letting
39the system know about hardware-disabled states that may be implemented on
40the device.
41 41
42The rfkill-input code implements a basic response to rfkill buttons -- it 42The rfkill core code also notifies userspace of state changes, and provides
43implements turning on/off all devices of a certain class (or all). 43ways for userspace to query the current states. See the "Userspace support"
44section below.
44 45
45When the device is hard-blocked (either by a call to rfkill_set_hw_state() 46When the device is hard-blocked (either by a call to rfkill_set_hw_state()
46or from query_hw_block) set_block() will be invoked but drivers can well 47or from query_hw_block) set_block() will be invoked for additional software
47ignore the method call since they can use the return value of the function 48block, but drivers can ignore the method call since they can use the return
48rfkill_set_hw_state() to sync the software state instead of keeping track 49value of the function rfkill_set_hw_state() to sync the software state
49of calls to set_block(). 50instead of keeping track of calls to set_block(). In fact, drivers should
50 51use the return value of rfkill_set_hw_state() unless the hardware actually
51 52keeps track of soft and hard block separately.
52The entire functionality is spread over more than one subsystem:
53
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)
59
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.
62
63 * The rfkill drivers turn off/on their transmitters as requested.
64
65 * The rfkill class will generate userspace notifications (uevents) to tell
66 userspace what the current state is.
67 53
68 54
553. Kernel API
69 56
703. Kernel driver guidelines
71 57
72 58Drivers for radio transmitters normally implement an rfkill driver.
73Drivers for radio transmitters normally implement only the rfkill class.
74These drivers may not unblock the transmitter based on own decisions, they
75should act on information provided by the rfkill class only.
76 59
77Platform drivers might implement input devices if the rfkill button is just 60Platform drivers might implement input devices if the rfkill button is just
78that, a button. If that button influences the hardware then you need to 61that, a button. If that button influences the hardware then you need to
79implement an rfkill class instead. This also applies if the platform provides 62implement an rfkill driver instead. This also applies if the platform provides
80a way to turn on/off the transmitter(s). 63a way to turn on/off the transmitter(s).
81 64
82During suspend/hibernation, transmitters should only be left enabled when 65For some platforms, it is possible that the hardware state changes during
83wake-on wlan or similar functionality requires it and the device wasn't 66suspend/hibernation, in which case it will be necessary to update the rfkill
84blocked before suspend/hibernate. Note that it may be necessary to update 67core with the current state is at resume time.
85the rfkill subsystem's idea of what the current state is at resume time if
86the state may have changed over suspend.
87
88 68
69To create an rfkill driver, driver's Kconfig needs to have
89 70
904. Kernel API 71 depends on RFKILL || !RFKILL
91 72
92To build a driver with rfkill subsystem support, the driver should depend on 73to ensure the driver cannot be built-in when rfkill is modular. The !RFKILL
93(or select) the Kconfig symbol RFKILL. 74case allows the driver to be built when rfkill is not configured, which which
94 75case all rfkill API can still be used but will be provided by static inlines
95The hardware the driver talks to may be write-only (where the current state 76which compile to almost nothing.
96of the hardware is unknown), or read-write (where the hardware can be queried
97about its current state).
98 77
99Calling rfkill_set_hw_state() when a state change happens is required from 78Calling rfkill_set_hw_state() when a state change happens is required from
100rfkill drivers that control devices that can be hard-blocked unless they also 79rfkill drivers that control devices that can be hard-blocked unless they also
@@ -105,10 +84,33 @@ device). Don't do this unless you cannot get the event in any other way.
105 84
1065. Userspace support 855. Userspace support
107 86
108The following sysfs entries exist for every rfkill device: 87The recommended userspace interface to use is /dev/rfkill, which is a misc
88character device that allows userspace to obtain and set the state of rfkill
89devices and sets of devices. It also notifies userspace about device addition
90and removal. The API is a simple read/write API that is defined in
91linux/rfkill.h, with one ioctl that allows turning off the deprecated input
92handler in the kernel for the transition period.
93
94Except for the one ioctl, communication with the kernel is done via read()
95and write() of instances of 'struct rfkill_event'. In this structure, the
96soft and hard block are properly separated (unlike sysfs, see below) and
97userspace is able to get a consistent snapshot of all rfkill devices in the
98system. Also, it is possible to switch all rfkill drivers (or all drivers of
99a specified type) into a state which also updates the default state for
100hotplugged devices.
101
102After an application opens /dev/rfkill, it can read the current state of
103all devices, and afterwards can poll the descriptor for hotplug or state
104change events.
105
106Applications must ignore operations (the "op" field) they do not handle,
107this allows the API to be extended in the future.
108
109Additionally, each rfkill device is registered in sysfs and there has the
110following attributes:
109 111
110 name: Name assigned by driver to this key (interface or driver name). 112 name: Name assigned by driver to this key (interface or driver name).
111 type: Name of the key type ("wlan", "bluetooth", etc). 113 type: Driver type string ("wlan", "bluetooth", etc).
112 state: Current state of the transmitter 114 state: Current state of the transmitter
113 0: RFKILL_STATE_SOFT_BLOCKED 115 0: RFKILL_STATE_SOFT_BLOCKED
114 transmitter is turned off by software 116 transmitter is turned off by software
@@ -117,7 +119,12 @@ The following sysfs entries exist for every rfkill device:
117 2: RFKILL_STATE_HARD_BLOCKED 119 2: RFKILL_STATE_HARD_BLOCKED
118 transmitter is forced off by something outside of 120 transmitter is forced off by something outside of
119 the driver's control. 121 the driver's control.
120 claim: 0: Kernel handles events (currently always reads that value) 122 This file is deprecated because it can only properly show
123 three of the four possible states, soft-and-hard-blocked is
124 missing.
125 claim: 0: Kernel handles events
126 This file is deprecated because there no longer is a way to
127 claim just control over a single rfkill instance.
121 128
122rfkill devices also issue uevents (with an action of "change"), with the 129rfkill devices also issue uevents (with an action of "change"), with the
123following environment variables set: 130following environment variables set:
@@ -128,9 +135,3 @@ RFKILL_TYPE
128 135
129The contents of these variables corresponds to the "name", "state" and 136The contents of these variables corresponds to the "name", "state" and
130"type" sysfs files explained above. 137"type" sysfs files explained above.
131
132An alternative userspace interface exists as a misc device /dev/rfkill,
133which allows userspace to obtain and set the state of rfkill devices and
134sets of devices. It also notifies userspace about device addition and
135removal. The API is a simple read/write API that is defined in
136linux/rfkill.h.