blob: 1b74b5f30af4b5c8180dbfd2e2b3cacbe99fa8c9 [file] [log] [blame]
Johannes Berg19d337d2009-06-02 13:01:37 +02001rfkill - RF kill switch support
2===============================
Ivo van Doorndac24ab2007-09-13 09:22:55 +02003
Johannes Berg19d337d2009-06-02 13:01:37 +020041. Introduction
52. Implementation details
63. Kernel driver guidelines
74. Kernel API
85. Userspace support
Ivo van Doorndac24ab2007-09-13 09:22:55 +02009
Henrique de Moraes Holschuhdc288522008-06-23 17:23:08 -030010
Johannes Berg19d337d2009-06-02 13:01:37 +0200111. Introduction
Ivo van Doorndac24ab2007-09-13 09:22:55 +020012
Johannes Berg19d337d2009-06-02 13:01:37 +020013The rfkill subsystem provides a generic interface to disabling any radio
14transmitter in the system. When a transmitter is blocked, it shall not
15radiate any power.
Henrique de Moraes Holschuhf3146af2008-06-23 17:22:56 -030016
Johannes Berg19d337d2009-06-02 13:01:37 +020017The subsystem also provides the ability to react on button presses and
18disable all transmitters of a certain type (or all). This is intended for
19situations where transmitters need to be turned off, for example on
20aircraft.
Henrique de Moraes Holschuhf7983f72008-06-23 17:46:43 -030021
Henrique de Moraes Holschuhf3146af2008-06-23 17:22:56 -030022
Henrique de Moraes Holschuhdc288522008-06-23 17:23:08 -030023
Johannes Berg19d337d2009-06-02 13:01:37 +0200242. Implementation details
Henrique de Moraes Holschuhdc288522008-06-23 17:23:08 -030025
Henrique de Moraes Holschuhf7983f72008-06-23 17:46:43 -030026The rfkill subsystem is composed of various components: the rfkill class, the
27rfkill-input module (an input layer handler), and some specific input layer
28events.
29
Johannes Berg19d337d2009-06-02 13:01:37 +020030The rfkill class is provided for kernel drivers to register their radio
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".
Henrique de Moraes Holschuhf7983f72008-06-23 17:46:43 -030035
Johannes Berg19d337d2009-06-02 13:01:37 +020036The 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.
Henrique de Moraes Holschuhdc288522008-06-23 17:23:08 -030040
Henrique de Moraes Holschuhf7983f72008-06-23 17:46:43 -030041
Johannes Berg19d337d2009-06-02 13:01:37 +020042The rfkill-input code implements a basic response to rfkill buttons -- it
43implements turning on/off all devices of a certain class (or all).
Henrique de Moraes Holschuhdc288522008-06-23 17:23:08 -030044
Johannes Berg19d337d2009-06-02 13:01:37 +020045When 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
47ignore the method call since they can use the return value of the function
48rfkill_set_hw_state() to sync the software state instead of keeping track
49of calls to set_block().
Henrique de Moraes Holschuhdc288522008-06-23 17:23:08 -030050
Ivo van Doorndac24ab2007-09-13 09:22:55 +020051
Johannes Berg19d337d2009-06-02 13:01:37 +020052The entire functionality is spread over more than one subsystem:
Ivo van Doorndac24ab2007-09-13 09:22:55 +020053
Johannes Berg19d337d2009-06-02 13:01:37 +020054 * 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)
Ivo van Doorndac24ab2007-09-13 09:22:55 +020059
Johannes Berg19d337d2009-06-02 13:01:37 +020060 * 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.
Ivo van Doorndac24ab2007-09-13 09:22:55 +020062
Johannes Berg19d337d2009-06-02 13:01:37 +020063 * The rfkill drivers turn off/on their transmitters as requested.
Henrique de Moraes Holschuhf7983f72008-06-23 17:46:43 -030064
Johannes Berg19d337d2009-06-02 13:01:37 +020065 * The rfkill class will generate userspace notifications (uevents) to tell
66 userspace what the current state is.
Henrique de Moraes Holschuhf7983f72008-06-23 17:46:43 -030067
Henrique de Moraes Holschuhf7983f72008-06-23 17:46:43 -030068
Henrique de Moraes Holschuhf7983f72008-06-23 17:46:43 -030069
Johannes Berg19d337d2009-06-02 13:01:37 +0200703. Kernel driver guidelines
Henrique de Moraes Holschuhf7983f72008-06-23 17:46:43 -030071
Henrique de Moraes Holschuhf7983f72008-06-23 17:46:43 -030072
Johannes Berg19d337d2009-06-02 13:01:37 +020073Drivers 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.
Henrique de Moraes Holschuhf7983f72008-06-23 17:46:43 -030076
Johannes Berg19d337d2009-06-02 13:01:37 +020077Platform drivers might implement input devices if the rfkill button is just
78that, a button. If that button influences the hardware then you need to
79implement an rfkill class instead. This also applies if the platform provides
80a way to turn on/off the transmitter(s).
Henrique de Moraes Holschuhf7983f72008-06-23 17:46:43 -030081
Johannes Berg19d337d2009-06-02 13:01:37 +020082During suspend/hibernation, transmitters should only be left enabled when
83wake-on wlan or similar functionality requires it and the device wasn't
84blocked before suspend/hibernate. Note that it may be necessary to update
85the rfkill subsystem's idea of what the current state is at resume time if
86the state may have changed over suspend.
Henrique de Moraes Holschuhf7983f72008-06-23 17:46:43 -030087
Henrique de Moraes Holschuhf7983f72008-06-23 17:46:43 -030088
Henrique de Moraes Holschuh50056572008-06-23 17:46:42 -030089
Johannes Berg19d337d2009-06-02 13:01:37 +0200904. Kernel API
Henrique de Moraes Holschuhdc288522008-06-23 17:23:08 -030091
92To build a driver with rfkill subsystem support, the driver should depend on
Johannes Berg19d337d2009-06-02 13:01:37 +020093(or select) the Kconfig symbol RFKILL.
Henrique de Moraes Holschuhdc288522008-06-23 17:23:08 -030094
95The hardware the driver talks to may be write-only (where the current state
96of the hardware is unknown), or read-write (where the hardware can be queried
97about its current state).
98
Johannes Berg19d337d2009-06-02 13:01:37 +020099Calling 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
101assign the poll_hw_block() callback (then the rfkill core will poll the
102device). Don't do this unless you cannot get the event in any other way.
Henrique de Moraes Holschuh2fd9b222008-07-21 21:18:17 -0300103
Henrique de Moraes Holschuhdc288522008-06-23 17:23:08 -0300104
Henrique de Moraes Holschuhdc288522008-06-23 17:23:08 -0300105
Johannes Berg19d337d2009-06-02 13:01:37 +02001065. Userspace support
Henrique de Moraes Holschuh2fd9b222008-07-21 21:18:17 -0300107
Johannes Berg19d337d2009-06-02 13:01:37 +0200108The following sysfs entries exist for every rfkill device:
Ivo van Doorndac24ab2007-09-13 09:22:55 +0200109
110 name: Name assigned by driver to this key (interface or driver name).
111 type: Name of the key type ("wlan", "bluetooth", etc).
Henrique de Moraes Holschuh50056572008-06-23 17:46:42 -0300112 state: Current state of the transmitter
113 0: RFKILL_STATE_SOFT_BLOCKED
Johannes Berg19d337d2009-06-02 13:01:37 +0200114 transmitter is turned off by software
Henrique de Moraes Holschuh50056572008-06-23 17:46:42 -0300115 1: RFKILL_STATE_UNBLOCKED
Johannes Bergf71fea22009-06-03 10:17:59 +0200116 transmitter is (potentially) active
Henrique de Moraes Holschuh50056572008-06-23 17:46:42 -0300117 2: RFKILL_STATE_HARD_BLOCKED
118 transmitter is forced off by something outside of
Johannes Berg19d337d2009-06-02 13:01:37 +0200119 the driver's control.
120 claim: 0: Kernel handles events (currently always reads that value)
Ivo van Doorndac24ab2007-09-13 09:22:55 +0200121
Johannes Berg19d337d2009-06-02 13:01:37 +0200122rfkill devices also issue uevents (with an action of "change"), with the
123following environment variables set:
Henrique de Moraes Holschuhdc288522008-06-23 17:23:08 -0300124
Johannes Berg19d337d2009-06-02 13:01:37 +0200125RFKILL_NAME
126RFKILL_STATE
127RFKILL_TYPE
Henrique de Moraes Holschuhdc288522008-06-23 17:23:08 -0300128
Johannes Berg19d337d2009-06-02 13:01:37 +0200129The contents of these variables corresponds to the "name", "state" and
130"type" sysfs files explained above.
Johannes Bergf71fea22009-06-03 10:17:59 +0200131
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.