Documentation/rfkill.txt

   1 rfkill - RF switch subsystem support
   2 ====================================
   3
   4 1 Implementation details
   5 2 Driver support
   6 3 Userspace support
   7
   8 ===============================================================================
   9 1: Implementation details
  10
  11 The rfkill switch subsystem exists to add a generic interface to circuitry that
  12 can enable or disable the RF output of a radio *transmitter* of any type.
  13
  14 When a rfkill switch is in the RFKILL_STATE_ON, the radio transmitter is
  15 *enabled*.  When the rfkill switch is in the RFKILL_STATE_OFF, the radio
  16 transmitter is *disabled*.
  17
  18 The rfkill switch subsystem offers support for keys often found on laptops
  19 to enable wireless devices like WiFi and Bluetooth.
  20
  21 This is done by providing the user 3 possibilities:
  22  1 - The rfkill system handles all events; userspace is not aware of events.
  23  2 - The rfkill system handles all events; userspace is informed about the events.
  24  3 - The rfkill system does not handle events; userspace handles all events.
  25
  26 The buttons to enable and disable the wireless radios are important in
  27 situations where the user is for example using his laptop on a location where
  28 wireless radios _must_ be disabled (e.g. airplanes).
  29 Because of this requirement, userspace support for the keys should not be
  30 made mandatory. Because userspace might want to perform some additional smarter
  31 tasks when the key is pressed, rfkill still provides userspace the possibility
  32 to take over the task to handle the key events.
  33
  34 The system inside the kernel has been split into 2 separate sections:
  35         1 - RFKILL
  36         2 - RFKILL_INPUT
  37
  38 The first option enables rfkill support and will make sure userspace will
  39 be notified of any events through the input device. It also creates several
  40 sysfs entries which can be used by userspace. See section "Userspace support".
  41
  42 The second option provides an rfkill input handler. This handler will
  43 listen to all rfkill key events and will toggle the radio accordingly.
  44 With this option enabled userspace could either do nothing or simply
  45 perform monitoring tasks.
  46
  47 ====================================
  48 2: Driver support
  49
  50 To build a driver with rfkill subsystem support, the driver should
  51 depend on the Kconfig symbol RFKILL; it should _not_ depend on
  52 RKFILL_INPUT.
  53
  54 Unless key events trigger an interrupt to which the driver listens, polling
  55 will be required to determine the key state changes. For this the input
  56 layer providers the input-polldev handler.
  57
  58 A driver should implement a few steps to correctly make use of the
  59 rfkill subsystem. First for non-polling drivers:
  60
  61         - rfkill_allocate()
  62         - input_allocate_device()
  63         - rfkill_register()
  64         - input_register_device()
  65
  66 For polling drivers:
  67
  68         - rfkill_allocate()
  69         - input_allocate_polled_device()
  70         - rfkill_register()
  71         - input_register_polled_device()
  72
  73 When a key event has been detected, the correct event should be
  74 sent over the input device which has been registered by the driver.
  75
  76 ====================================
  77 3: Userspace support
  78
  79 For each key an input device will be created which will send out the correct
  80 key event when the rfkill key has been pressed.
  81
  82 The following sysfs entries will be created:
  83
  84         name: Name assigned by driver to this key (interface or driver name).
  85         type: Name of the key type ("wlan", "bluetooth", etc).
  86         state: Current state of the key. 1: On, 0: Off.
  87         claim: 1: Userspace handles events, 0: Kernel handles events
  88
  89 Both the "state" and "claim" entries are also writable. For the "state" entry
  90 this means that when 1 or 0 is written all radios, not yet in the requested
  91 state, will be will be toggled accordingly.
  92 For the "claim" entry writing 1 to it means that the kernel no longer handles
  93 key events even though RFKILL_INPUT input was enabled. When "claim" has been
  94 set to 0, userspace should make sure that it listens for the input events or
  95 check the sysfs "state" entry regularly to correctly perform the required
  96 tasks when the rkfill key is pressed.