blob: 427e89712f4a27c25117ce5bfe85d1ff7078300d [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
Henrique de Moraes Holschuhdc288522008-06-23 17:23:08 -030028
Johannes Berg19d337d2009-06-02 13:01:37 +0200292. Implementation details
Henrique de Moraes Holschuhdc288522008-06-23 17:23:08 -030030
Johannes Bergce0879e2009-06-15 15:36:38 +020031The rfkill subsystem is composed of three main components:
32 * the rfkill core,
33 * the deprecated rfkill-input module (an input layer handler, being
34 replaced by userspace policy code) and
35 * the rfkill drivers.
Henrique de Moraes Holschuhf7983f72008-06-23 17:46:43 -030036
Johannes Bergce0879e2009-06-15 15:36:38 +020037The 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.
Henrique de Moraes Holschuhf7983f72008-06-23 17:46:43 -030041
Johannes Bergce0879e2009-06-15 15:36:38 +020042The rfkill core code also notifies userspace of state changes, and provides
43ways for userspace to query the current states. See the "Userspace support"
44section below.
Henrique de Moraes Holschuhdc288522008-06-23 17:23:08 -030045
Johannes Berg19d337d2009-06-02 13:01:37 +020046When the device is hard-blocked (either by a call to rfkill_set_hw_state()
Johannes Bergce0879e2009-06-15 15:36:38 +020047or from query_hw_block) set_block() will be invoked for additional software
48block, but drivers can ignore the method call since they can use the return
49value of the function rfkill_set_hw_state() to sync the software state
50instead of keeping track of calls to set_block(). In fact, drivers should
51use the return value of rfkill_set_hw_state() unless the hardware actually
52keeps track of soft and hard block separately.
Henrique de Moraes Holschuhdc288522008-06-23 17:23:08 -030053
Ivo van Doorndac24ab2007-09-13 09:22:55 +020054
Johannes Bergce0879e2009-06-15 15:36:38 +0200553. Kernel API
Henrique de Moraes Holschuhf7983f72008-06-23 17:46:43 -030056
Henrique de Moraes Holschuhf7983f72008-06-23 17:46:43 -030057
Johannes Bergce0879e2009-06-15 15:36:38 +020058Drivers for radio transmitters normally implement an rfkill driver.
Henrique de Moraes Holschuhf7983f72008-06-23 17:46:43 -030059
Johannes Berg19d337d2009-06-02 13:01:37 +020060Platform drivers might implement input devices if the rfkill button is just
61that, a button. If that button influences the hardware then you need to
Johannes Bergce0879e2009-06-15 15:36:38 +020062implement an rfkill driver instead. This also applies if the platform provides
Johannes Berg19d337d2009-06-02 13:01:37 +020063a way to turn on/off the transmitter(s).
Henrique de Moraes Holschuhf7983f72008-06-23 17:46:43 -030064
Johannes Bergce0879e2009-06-15 15:36:38 +020065For some platforms, it is possible that the hardware state changes during
66suspend/hibernation, in which case it will be necessary to update the rfkill
67core with the current state is at resume time.
Henrique de Moraes Holschuhf7983f72008-06-23 17:46:43 -030068
Johannes Bergce0879e2009-06-15 15:36:38 +020069To create an rfkill driver, driver's Kconfig needs to have
Henrique de Moraes Holschuhf7983f72008-06-23 17:46:43 -030070
Johannes Bergce0879e2009-06-15 15:36:38 +020071 depends on RFKILL || !RFKILL
Henrique de Moraes Holschuh50056572008-06-23 17:46:42 -030072
Johannes Bergce0879e2009-06-15 15:36:38 +020073to ensure the driver cannot be built-in when rfkill is modular. The !RFKILL
Xishi Qiuc79a8d82013-11-06 13:18:21 -080074case allows the driver to be built when rfkill is not configured, which
Johannes Bergce0879e2009-06-15 15:36:38 +020075case all rfkill API can still be used but will be provided by static inlines
76which compile to almost nothing.
Henrique de Moraes Holschuhdc288522008-06-23 17:23:08 -030077
Johannes Berg19d337d2009-06-02 13:01:37 +020078Calling rfkill_set_hw_state() when a state change happens is required from
79rfkill drivers that control devices that can be hard-blocked unless they also
80assign the poll_hw_block() callback (then the rfkill core will poll the
81device). Don't do this unless you cannot get the event in any other way.
Henrique de Moraes Holschuh2fd9b222008-07-21 21:18:17 -030082
Henrique de Moraes Holschuhdc288522008-06-23 17:23:08 -030083
Henrique de Moraes Holschuhdc288522008-06-23 17:23:08 -030084
Johannes Berg19d337d2009-06-02 13:01:37 +0200855. Userspace support
Henrique de Moraes Holschuh2fd9b222008-07-21 21:18:17 -030086
Johannes Bergce0879e2009-06-15 15:36:38 +020087The 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
florian@mickler.org69c86372010-02-24 12:05:16 +0100102After an application opens /dev/rfkill, it can read the current state of all
103devices. Changes can be either obtained by either polling the descriptor for
104hotplug or state change events or by listening for uevents emitted by the
105rfkill core framework.
Johannes Bergce0879e2009-06-15 15:36:38 +0200106
florian@mickler.org69c86372010-02-24 12:05:16 +0100107Additionally, each rfkill device is registered in sysfs and emits uevents.
Johannes Bergce0879e2009-06-15 15:36:38 +0200108
florian@mickler.org69c86372010-02-24 12:05:16 +0100109rfkill devices issue uevents (with an action of "change"), with the following
110environment variables set:
Henrique de Moraes Holschuhdc288522008-06-23 17:23:08 -0300111
Johannes Berg19d337d2009-06-02 13:01:37 +0200112RFKILL_NAME
113RFKILL_STATE
114RFKILL_TYPE
Henrique de Moraes Holschuhdc288522008-06-23 17:23:08 -0300115
Johannes Berg19d337d2009-06-02 13:01:37 +0200116The contents of these variables corresponds to the "name", "state" and
117"type" sysfs files explained above.
florian@mickler.org69c86372010-02-24 12:05:16 +0100118
119
Paul Bolle395cf962011-08-15 02:02:26 +0200120For further details consult Documentation/ABI/stable/sysfs-class-rfkill.