Documentation/rfkill.txt

   1 rfkill - RF kill switch support
   2 ===============================
   3
   4 1. Introduction
   5 2. Implementation details
   6 3. Kernel driver guidelines
   7 4. Kernel API
   8 5. Userspace support
   9
  10
  11 1. Introduction
  12
  13 The rfkill subsystem provides a generic interface to disabling any radio
  14 transmitter in the system. When a transmitter is blocked, it shall not
  15 radiate any power.
  16
  17 The subsystem also provides the ability to react on button presses and
  18 disable all transmitters of a certain type (or all). This is intended for
  19 situations where transmitters need to be turned off, for example on
  20 aircraft.
  21
  22
  23
  24 2. Implementation details
  25
  26 The rfkill subsystem is composed of various components: the rfkill class, the
  27 rfkill-input module (an input layer handler), and some specific input layer
  28 events.
  29
  30 The rfkill class is provided for kernel drivers to register their radio
  31 transmitter with the kernel, provide methods for turning it on and off and,
  32 optionally, letting the system know about hardware-disabled states that may
  33 be implemented on the device. This code is enabled with the CONFIG_RFKILL
  34 Kconfig option, which drivers can "select".
  35
  36 The rfkill class code also notifies userspace of state changes, this is
  37 achieved via uevents. It also provides some sysfs files for userspace to
  38 check the status of radio transmitters. See the "Userspace support" section
  39 below.
  40
  41
  42 The rfkill-input code implements a basic response to rfkill buttons -- it
  43 implements turning on/off all devices of a certain class (or all).
  44
  45 When the device is hard-blocked (either by a call to rfkill_set_hw_state()
  46 or from query_hw_block) set_block() will be invoked but drivers can well
  47 ignore the method call since they can use the return value of the function
  48 rfkill_set_hw_state() to sync the software state instead of keeping track
  49 of calls to set_block().
  50
  51
  52 The entire functionality is spread over more than one subsystem:
  53
  54  * The kernel input layer generates KEY_WWAN, KEY_WLAN etc. and
  55    SW_RFKILL_ALL -- when the user presses a button. Drivers for radio
  56    transmitters generally do not register to the input layer, unless the
  57    device really provides an input device (i.e. a button that has no
  58    effect other than generating a button press event)
  59
  60  * The rfkill-input code hooks up to these events and switches the soft-block
  61    of the various radio transmitters, depending on the button type.
  62
  63  * The rfkill drivers turn off/on their transmitters as requested.
  64
  65  * The rfkill class will generate userspace notifications (uevents) to tell
  66    userspace what the current state is.
  67
  68
  69
  70 3. Kernel driver guidelines
  71
  72
  73 Drivers for radio transmitters normally implement only the rfkill class.
  74 These drivers may not unblock the transmitter based on own decisions, they
  75 should act on information provided by the rfkill class only.
  76
  77 Platform drivers might implement input devices if the rfkill button is just
  78 that, a button. If that button influences the hardware then you need to
  79 implement an rfkill class instead. This also applies if the platform provides
  80 a way to turn on/off the transmitter(s).
  81
  82 During suspend/hibernation, transmitters should only be left enabled when
  83 wake-on wlan or similar functionality requires it and the device wasn't
  84 blocked before suspend/hibernate. Note that it may be necessary to update
  85 the rfkill subsystem's idea of what the current state is at resume time if
  86 the state may have changed over suspend.
  87
  88
  89
  90 4. Kernel API
  91
  92 To build a driver with rfkill subsystem support, the driver should depend on
  93 (or select) the Kconfig symbol RFKILL.
  94
  95 The hardware the driver talks to may be write-only (where the current state
  96 of the hardware is unknown), or read-write (where the hardware can be queried
  97 about its current state).
  98
  99 Calling rfkill_set_hw_state() when a state change happens is required from
 100 rfkill drivers that control devices that can be hard-blocked unless they also
 101 assign the poll_hw_block() callback (then the rfkill core will poll the
 102 device). Don't do this unless you cannot get the event in any other way.
 103
 104
 105
 106 5. Userspace support
 107
 108 The following sysfs entries exist for every rfkill device:
 109
 110         name: Name assigned by driver to this key (interface or driver name).
 111         type: Name of the key type ("wlan", "bluetooth", etc).
 112         state: Current state of the transmitter
 113                 0: RFKILL_STATE_SOFT_BLOCKED
 114                         transmitter is turned off by software
 115                 1: RFKILL_STATE_UNBLOCKED
 116                         transmitter is (potentially) active
 117                 2: RFKILL_STATE_HARD_BLOCKED
 118                         transmitter is forced off by something outside of
 119                         the driver's control.
 120         claim: 0: Kernel handles events (currently always reads that value)
 121
 122 rfkill devices also issue uevents (with an action of "change"), with the
 123 following environment variables set:
 124
 125 RFKILL_NAME
 126 RFKILL_STATE
 127 RFKILL_TYPE
 128
 129 The contents of these variables corresponds to the "name", "state" and
 130 "type" sysfs files explained above.
 131
 132 An alternative userspace interface exists as a misc device /dev/rfkill,
 133 which allows userspace to obtain and set the state of rfkill devices and
 134 sets of devices. It also notifies userspace about device addition and
 135 removal. The API is a simple read/write API that is defined in
 136 linux/rfkill.h.