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