blob: 2ee6ef9a6554d600088ae572b3256ffe44e51d08 [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
Johannes Bergce0879e2009-06-15 15:36:38 +020063. Kernel API
74. Userspace support
Ivo van Doorndac24ab2007-09-13 09:22:55 +02008
Henrique de Moraes Holschuhdc288522008-06-23 17:23:08 -03009
Johannes Berg19d337d2009-06-02 13:01:37 +0200101. Introduction
Ivo van Doorndac24ab2007-09-13 09:22:55 +020011
Johannes Berg19d337d2009-06-02 13:01:37 +020012The rfkill subsystem provides a generic interface to disabling any radio
13transmitter in the system. When a transmitter is blocked, it shall not
14radiate any power.
Henrique de Moraes Holschuhf3146af2008-06-23 17:22:56 -030015
Johannes Berg19d337d2009-06-02 13:01:37 +020016The subsystem also provides the ability to react on button presses and
17disable all transmitters of a certain type (or all). This is intended for
18situations where transmitters need to be turned off, for example on
19aircraft.
Henrique de Moraes Holschuhf7983f72008-06-23 17:46:43 -030020
Johannes Bergce0879e2009-06-15 15:36:38 +020021The 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:
Carlos Garciac98be0c2014-04-04 22:31:00 -040024 - hard block: read-only radio block that cannot be overridden by software
Johannes Bergce0879e2009-06-15 15:36:38 +020025 - soft block: writable radio block (need not be readable) that is set by
26 the system software.
Henrique de Moraes Holschuhf3146af2008-06-23 17:22:56 -030027
Andrew Clausen0efbb782015-01-09 20:24:55 +000028The rfkill subsystem has two parameters, rfkill.default_state and
29rfkill.master_switch_mode, which are documented in kernel-parameters.txt.
30
Henrique de Moraes Holschuhdc288522008-06-23 17:23:08 -030031
Johannes Berg19d337d2009-06-02 13:01:37 +0200322. Implementation details
Henrique de Moraes Holschuhdc288522008-06-23 17:23:08 -030033
Johannes Bergce0879e2009-06-15 15:36:38 +020034The rfkill subsystem is composed of three main components:
35 * the rfkill core,
36 * the deprecated rfkill-input module (an input layer handler, being
37 replaced by userspace policy code) and
38 * the rfkill drivers.
Henrique de Moraes Holschuhf7983f72008-06-23 17:46:43 -030039
Johannes Bergce0879e2009-06-15 15:36:38 +020040The rfkill core provides API for kernel drivers to register their radio
41transmitter with the kernel, methods for turning it on and off and, letting
42the system know about hardware-disabled states that may be implemented on
43the device.
Henrique de Moraes Holschuhf7983f72008-06-23 17:46:43 -030044
Johannes Bergce0879e2009-06-15 15:36:38 +020045The rfkill core code also notifies userspace of state changes, and provides
46ways for userspace to query the current states. See the "Userspace support"
47section below.
Henrique de Moraes Holschuhdc288522008-06-23 17:23:08 -030048
Johannes Berg19d337d2009-06-02 13:01:37 +020049When the device is hard-blocked (either by a call to rfkill_set_hw_state()
Johannes Bergce0879e2009-06-15 15:36:38 +020050or from query_hw_block) set_block() will be invoked for additional software
51block, but drivers can ignore the method call since they can use the return
52value of the function rfkill_set_hw_state() to sync the software state
53instead of keeping track of calls to set_block(). In fact, drivers should
54use the return value of rfkill_set_hw_state() unless the hardware actually
55keeps track of soft and hard block separately.
Henrique de Moraes Holschuhdc288522008-06-23 17:23:08 -030056
Ivo van Doorndac24ab2007-09-13 09:22:55 +020057
Johannes Bergce0879e2009-06-15 15:36:38 +0200583. Kernel API
Henrique de Moraes Holschuhf7983f72008-06-23 17:46:43 -030059
Henrique de Moraes Holschuhf7983f72008-06-23 17:46:43 -030060
Johannes Bergce0879e2009-06-15 15:36:38 +020061Drivers for radio transmitters normally implement an rfkill driver.
Henrique de Moraes Holschuhf7983f72008-06-23 17:46:43 -030062
Johannes Berg19d337d2009-06-02 13:01:37 +020063Platform drivers might implement input devices if the rfkill button is just
64that, a button. If that button influences the hardware then you need to
Johannes Bergce0879e2009-06-15 15:36:38 +020065implement an rfkill driver instead. This also applies if the platform provides
Johannes Berg19d337d2009-06-02 13:01:37 +020066a way to turn on/off the transmitter(s).
Henrique de Moraes Holschuhf7983f72008-06-23 17:46:43 -030067
Johannes Bergce0879e2009-06-15 15:36:38 +020068For some platforms, it is possible that the hardware state changes during
69suspend/hibernation, in which case it will be necessary to update the rfkill
70core with the current state is at resume time.
Henrique de Moraes Holschuhf7983f72008-06-23 17:46:43 -030071
Johannes Bergce0879e2009-06-15 15:36:38 +020072To create an rfkill driver, driver's Kconfig needs to have
Henrique de Moraes Holschuhf7983f72008-06-23 17:46:43 -030073
Johannes Bergce0879e2009-06-15 15:36:38 +020074 depends on RFKILL || !RFKILL
Henrique de Moraes Holschuh50056572008-06-23 17:46:42 -030075
Johannes Bergce0879e2009-06-15 15:36:38 +020076to ensure the driver cannot be built-in when rfkill is modular. The !RFKILL
Xishi Qiuc79a8d82013-11-06 13:18:21 -080077case allows the driver to be built when rfkill is not configured, which
Johannes Bergce0879e2009-06-15 15:36:38 +020078case all rfkill API can still be used but will be provided by static inlines
79which compile to almost nothing.
Henrique de Moraes Holschuhdc288522008-06-23 17:23:08 -030080
Johannes Berg19d337d2009-06-02 13:01:37 +020081Calling rfkill_set_hw_state() when a state change happens is required from
82rfkill drivers that control devices that can be hard-blocked unless they also
83assign the poll_hw_block() callback (then the rfkill core will poll the
84device). Don't do this unless you cannot get the event in any other way.
Henrique de Moraes Holschuh2fd9b222008-07-21 21:18:17 -030085
Henrique de Moraes Holschuhdc288522008-06-23 17:23:08 -030086
Henrique de Moraes Holschuhdc288522008-06-23 17:23:08 -030087
Johannes Berg19d337d2009-06-02 13:01:37 +0200885. Userspace support
Henrique de Moraes Holschuh2fd9b222008-07-21 21:18:17 -030089
Johannes Bergce0879e2009-06-15 15:36:38 +020090The recommended userspace interface to use is /dev/rfkill, which is a misc
91character device that allows userspace to obtain and set the state of rfkill
92devices and sets of devices. It also notifies userspace about device addition
93and removal. The API is a simple read/write API that is defined in
94linux/rfkill.h, with one ioctl that allows turning off the deprecated input
95handler in the kernel for the transition period.
96
97Except for the one ioctl, communication with the kernel is done via read()
98and write() of instances of 'struct rfkill_event'. In this structure, the
99soft and hard block are properly separated (unlike sysfs, see below) and
100userspace is able to get a consistent snapshot of all rfkill devices in the
101system. Also, it is possible to switch all rfkill drivers (or all drivers of
102a specified type) into a state which also updates the default state for
103hotplugged devices.
104
florian@mickler.org69c86372010-02-24 12:05:16 +0100105After an application opens /dev/rfkill, it can read the current state of all
106devices. Changes can be either obtained by either polling the descriptor for
107hotplug or state change events or by listening for uevents emitted by the
108rfkill core framework.
Johannes Bergce0879e2009-06-15 15:36:38 +0200109
florian@mickler.org69c86372010-02-24 12:05:16 +0100110Additionally, each rfkill device is registered in sysfs and emits uevents.
Johannes Bergce0879e2009-06-15 15:36:38 +0200111
florian@mickler.org69c86372010-02-24 12:05:16 +0100112rfkill devices issue uevents (with an action of "change"), with the following
113environment variables set:
Henrique de Moraes Holschuhdc288522008-06-23 17:23:08 -0300114
Johannes Berg19d337d2009-06-02 13:01:37 +0200115RFKILL_NAME
116RFKILL_STATE
117RFKILL_TYPE
Henrique de Moraes Holschuhdc288522008-06-23 17:23:08 -0300118
Johannes Berg19d337d2009-06-02 13:01:37 +0200119The contents of these variables corresponds to the "name", "state" and
120"type" sysfs files explained above.
florian@mickler.org69c86372010-02-24 12:05:16 +0100121
122
Paul Bolle395cf962011-08-15 02:02:26 +0200123For further details consult Documentation/ABI/stable/sysfs-class-rfkill.