| 1 | ===============================
|
| 2 | rfkill - RF kill switch support
|
| 3 | ===============================
|
| 4 |
|
| 5 |
|
| 6 | .. contents::
|
| 7 | :depth: 2
|
| 8 |
|
| 9 | Introduction
|
| 10 | ============
|
| 11 |
|
| 12 | The rfkill subsystem provides a generic interface for disabling any radio
|
| 13 | transmitter in the system. When a transmitter is blocked, it shall not
|
| 14 | radiate any power.
|
| 15 |
|
| 16 | The subsystem also provides the ability to react on button presses and
|
| 17 | disable all transmitters of a certain type (or all). This is intended for
|
| 18 | situations where transmitters need to be turned off, for example on
|
| 19 | aircraft.
|
| 20 |
|
| 21 | The rfkill subsystem has a concept of "hard" and "soft" block, which
|
| 22 | differ little in their meaning (block == transmitters off) but rather in
|
| 23 | whether they can be changed or not:
|
| 24 |
|
| 25 | - hard block
|
| 26 | read-only radio block that cannot be overridden by software
|
| 27 |
|
| 28 | - soft block
|
| 29 | writable radio block (need not be readable) that is set by
|
| 30 | the system software.
|
| 31 |
|
| 32 | The rfkill subsystem has two parameters, rfkill.default_state and
|
| 33 | rfkill.master_switch_mode, which are documented in
|
| 34 | admin-guide/kernel-parameters.rst.
|
| 35 |
|
| 36 |
|
| 37 | Implementation details
|
| 38 | ======================
|
| 39 |
|
| 40 | The rfkill subsystem is composed of three main components:
|
| 41 |
|
| 42 | * the rfkill core,
|
| 43 | * the deprecated rfkill-input module (an input layer handler, being
|
| 44 | replaced by userspace policy code) and
|
| 45 | * the rfkill drivers.
|
| 46 |
|
| 47 | The rfkill core provides API for kernel drivers to register their radio
|
| 48 | transmitter with the kernel, methods for turning it on and off, and letting
|
| 49 | the system know about hardware-disabled states that may be implemented on
|
| 50 | the device.
|
| 51 |
|
| 52 | The rfkill core code also notifies userspace of state changes, and provides
|
| 53 | ways for userspace to query the current states. See the "Userspace support"
|
| 54 | section below.
|
| 55 |
|
| 56 | When the device is hard-blocked (either by a call to rfkill_set_hw_state()
|
| 57 | or from query_hw_block), set_block() will be invoked for additional software
|
| 58 | block, but drivers can ignore the method call since they can use the return
|
| 59 | value of the function rfkill_set_hw_state() to sync the software state
|
| 60 | instead of keeping track of calls to set_block(). In fact, drivers should
|
| 61 | use the return value of rfkill_set_hw_state() unless the hardware actually
|
| 62 | keeps track of soft and hard block separately.
|
| 63 |
|
| 64 |
|
| 65 | Kernel API
|
| 66 | ==========
|
| 67 |
|
| 68 | Drivers for radio transmitters normally implement an rfkill driver.
|
| 69 |
|
| 70 | Platform drivers might implement input devices if the rfkill button is just
|
| 71 | that, a button. If that button influences the hardware then you need to
|
| 72 | implement an rfkill driver instead. This also applies if the platform provides
|
| 73 | a way to turn on/off the transmitter(s).
|
| 74 |
|
| 75 | For some platforms, it is possible that the hardware state changes during
|
| 76 | suspend/hibernation, in which case it will be necessary to update the rfkill
|
| 77 | core with the current state at resume time.
|
| 78 |
|
| 79 | To create an rfkill driver, driver's Kconfig needs to have::
|
| 80 |
|
| 81 | depends on RFKILL || !RFKILL
|
| 82 |
|
| 83 | to ensure the driver cannot be built-in when rfkill is modular. The !RFKILL
|
| 84 | case allows the driver to be built when rfkill is not configured, in which
|
| 85 | case all rfkill API can still be used but will be provided by static inlines
|
| 86 | which compile to almost nothing.
|
| 87 |
|
| 88 | Calling rfkill_set_hw_state() when a state change happens is required from
|
| 89 | rfkill drivers that control devices that can be hard-blocked unless they also
|
| 90 | assign the poll_hw_block() callback (then the rfkill core will poll the
|
| 91 | device). Don't do this unless you cannot get the event in any other way.
|
| 92 |
|
| 93 | rfkill provides per-switch LED triggers, which can be used to drive LEDs
|
| 94 | according to the switch state (LED_FULL when blocked, LED_OFF otherwise).
|
| 95 |
|
| 96 |
|
| 97 | Userspace support
|
| 98 | =================
|
| 99 |
|
| 100 | The recommended userspace interface to use is /dev/rfkill, which is a misc
|
| 101 | character device that allows userspace to obtain and set the state of rfkill
|
| 102 | devices and sets of devices. It also notifies userspace about device addition
|
| 103 | and removal. The API is a simple read/write API that is defined in
|
| 104 | linux/rfkill.h, with one ioctl that allows turning off the deprecated input
|
| 105 | handler in the kernel for the transition period.
|
| 106 |
|
| 107 | Except for the one ioctl, communication with the kernel is done via read()
|
| 108 | and write() of instances of 'struct rfkill_event'. In this structure, the
|
| 109 | soft and hard block are properly separated (unlike sysfs, see below) and
|
| 110 | userspace is able to get a consistent snapshot of all rfkill devices in the
|
| 111 | system. Also, it is possible to switch all rfkill drivers (or all drivers of
|
| 112 | a specified type) into a state which also updates the default state for
|
| 113 | hotplugged devices.
|
| 114 |
|
| 115 | After an application opens /dev/rfkill, it can read the current state of all
|
| 116 | devices. Changes can be obtained by either polling the descriptor for
|
| 117 | hotplug or state change events or by listening for uevents emitted by the
|
| 118 | rfkill core framework.
|
| 119 |
|
| 120 | Additionally, each rfkill device is registered in sysfs and emits uevents.
|
| 121 |
|
| 122 | rfkill devices issue uevents (with an action of "change"), with the following
|
| 123 | environment variables set::
|
| 124 |
|
| 125 | RFKILL_NAME
|
| 126 | RFKILL_STATE
|
| 127 | RFKILL_TYPE
|
| 128 |
|
| 129 | The content of these variables corresponds to the "name", "state" and
|
| 130 | "type" sysfs files explained above.
|
| 131 |
|
| 132 | For further details consult Documentation/ABI/stable/sysfs-class-rfkill.
|