rfkill: document /dev/rfkill
[linux-2.6.git] / Documentation / rfkill.txt
1 rfkill - RF kill switch support
2 ===============================
3
4 1. Introduction
5 2. Implementation details
6 3. Kernel driver guidelines
7 4. Kernel API
8 5. Userspace support
9
10
11 1. Introduction
12
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.
16
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.
21
22
23
24 2. Implementation details
25
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
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".
35
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.
40
41
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).
44
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().
50
51
52 The 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
68
69
70 3. Kernel driver guidelines
71
72
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.
76
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).
81
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.
87
88
89
90 4. Kernel API
91
92 To build a driver with rfkill subsystem support, the driver should depend on
93 (or select) the Kconfig symbol RFKILL.
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
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.
103
104
105
106 5. Userspace support
107
108 The following sysfs entries exist for every rfkill device:
109
110         name: Name assigned by driver to this key (interface or driver name).
111         type: Name of the key type ("wlan", "bluetooth", etc).
112         state: Current state of the transmitter
113                 0: RFKILL_STATE_SOFT_BLOCKED
114                         transmitter is turned off by software
115                 1: RFKILL_STATE_UNBLOCKED
116                         transmitter is (potentially) active
117                 2: RFKILL_STATE_HARD_BLOCKED
118                         transmitter is forced off by something outside of
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.
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.