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