Eric Lee / smarc-ti-linux-kernel

Download as
Browse Code ยป

Commit dac24ab396fc92985060d5cb3c467d2d0ffc0c20

Authored by Ivo van Doorn
Committed by David S. Miller
1 parent e0665486b7
Exists in master and in 20 other branches dlt-processor-sdk-linux-03.00.00.04, newt-ti-linux-3.12.y, processor-sdk-linux-01.00.00, processor-sdk-linux-02.00.01, smarc-ti-linux-3.12.10, smarc-ti-linux-3.12.y, smarc-ti-linux-3.14.y, smarc-ti-linux-3.15.y, smarc-ti-lsk-linux-4.1.y, smarct3x-processor-sdk-04.01.00.06, smarct3x-processor-sdk-linux-02.00.01, smarct3x-processor-sdk-linux-03.00.00.04, smarct4x-800-processor-sdk-linux-02.00.01, smarct4x-processor-sdk-04.01.00.06, smarct4x-processor-sdk-linux-02.00.01, smarct4x-processor-sdk-linux-03.00.00.04, ti-linux-3.12.y, ti-linux-3.14.y, ti-linux-3.15.y, ti-lsk-linux-4.1.y

[RFKILL]: Add rfkill documentation 

Add a documentation file which contains
a short description about rfkill with some
notes about drivers and the userspace interface.

Changes since v1 and v2:
 - Spellchecking

Signed-off-by: Ivo van Doorn <IvDoorn@gmail.com>
Acked-by: Dmitry Torokhov <dtor@mail.ru>
Acked-by: Randy Dunlap <randy.dunlap@oracle.com>

Showing 1 changed file with 89 additions and 0 deletions Side-by-side Diff

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