blob: 8c174063b3f0cdf52956a94a5055865c093176cb [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
Mauro Carvalho Chehab8c27ceff32016-10-18 10:12:27 -020029rfkill.master_switch_mode, which are documented in admin-guide/kernel-parameters.rst.
Andrew Clausen0efbb782015-01-09 20:24:55 +000030
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
João Paulo Rechi Vita50ee7382016-02-22 11:36:37 -050086RFKill provides per-switch LED triggers, which can be used to drive LEDs
87according to the switch state (LED_FULL when blocked, LED_OFF otherwise).
Henrique de Moraes Holschuhdc288522008-06-23 17:23:08 -030088
Henrique de Moraes Holschuhdc288522008-06-23 17:23:08 -030089
Johannes Berg19d337d2009-06-02 13:01:37 +0200905. Userspace support
Henrique de Moraes Holschuh2fd9b222008-07-21 21:18:17 -030091
Johannes Bergce0879e2009-06-15 15:36:38 +020092The recommended userspace interface to use is /dev/rfkill, which is a misc
93character device that allows userspace to obtain and set the state of rfkill
94devices and sets of devices. It also notifies userspace about device addition
95and removal. The API is a simple read/write API that is defined in
96linux/rfkill.h, with one ioctl that allows turning off the deprecated input
97handler in the kernel for the transition period.
98
99Except for the one ioctl, communication with the kernel is done via read()
100and write() of instances of 'struct rfkill_event'. In this structure, the
101soft and hard block are properly separated (unlike sysfs, see below) and
102userspace is able to get a consistent snapshot of all rfkill devices in the
103system. Also, it is possible to switch all rfkill drivers (or all drivers of
104a specified type) into a state which also updates the default state for
105hotplugged devices.
106
florian@mickler.org69c86372010-02-24 12:05:16 +0100107After an application opens /dev/rfkill, it can read the current state of all
108devices. Changes can be either obtained by either polling the descriptor for
109hotplug or state change events or by listening for uevents emitted by the
110rfkill core framework.
Johannes Bergce0879e2009-06-15 15:36:38 +0200111
florian@mickler.org69c86372010-02-24 12:05:16 +0100112Additionally, each rfkill device is registered in sysfs and emits uevents.
Johannes Bergce0879e2009-06-15 15:36:38 +0200113
florian@mickler.org69c86372010-02-24 12:05:16 +0100114rfkill devices issue uevents (with an action of "change"), with the following
115environment variables set:
Henrique de Moraes Holschuhdc288522008-06-23 17:23:08 -0300116
Johannes Berg19d337d2009-06-02 13:01:37 +0200117RFKILL_NAME
118RFKILL_STATE
119RFKILL_TYPE
Henrique de Moraes Holschuhdc288522008-06-23 17:23:08 -0300120
Johannes Berg19d337d2009-06-02 13:01:37 +0200121The contents of these variables corresponds to the "name", "state" and
122"type" sysfs files explained above.
florian@mickler.org69c86372010-02-24 12:05:16 +0100123
124
Paul Bolle395cf962011-08-15 02:02:26 +0200125For further details consult Documentation/ABI/stable/sysfs-class-rfkill.