Improve the documentation of how to use the rfkill class in kernel drivers,
based on the doubts that came up in a thread in linux-wireless.
Signed-off-by: NHenrique de Moraes Holschuh <hmh@hmh.eng.br>
Acked-by: NIvo van Doorn <IvDoorn@gmail.com>
Signed-off-by: NJohn W. Linville <linville@tuxdriver.com>

The current naming of rfkill_state causes a lot of confusion: not only the
"kill" in rfkill suggests negative logic, but also the fact that rfkill cannot
turn anything on (it can just force something off or stop forcing something
off) is often forgotten.

Rename RFKILL_STATE_OFF to RFKILL_STATE_SOFT_BLOCKED (transmitter is blocked
and will not operate; state can be changed by a toggle_radio request), and
RFKILL_STATE_ON to RFKILL_STATE_UNBLOCKED (transmitter is not blocked, and may
operate).

Also, add a new third state, RFKILL_STATE_HARD_BLOCKED (transmitter is blocked
and will not operate; state cannot be changed through a toggle_radio request),
which is used by drivers to indicate a wireless transmiter was blocked by a
hardware rfkill line that accepts no overrides.

Keep the old names as #defines, but document them as deprecated.  This way,
drivers can be converted to the new names *and* verified to actually use rfkill
correctly one by one.
Signed-off-by: NHenrique de Moraes Holschuh <hmh@hmh.eng.br>
Acked-by: NIvo van Doorn <IvDoorn@gmail.com>
Signed-off-by: NJohn W. Linville <linville@tuxdriver.com>

Rework the documentation so as to make sure driver writers understand
exactly where the boundaries are for input drivers related to rfkill
switches, buttons and keys, and rfkill class drivers.

Also fix a small error in the documentation: setting the state of a normal
instance of the rfkill class does not affect the state of any other devices
(unless they are tied by firmware/hardware somehow).
Signed-off-by: NHenrique de Moraes Holschuh <hmh@hmh.eng.br>
Acked-by: NIvo van Doorn <IvDoorn@gmail.com>
Cc: Dmitry Torokhov <dtor@mail.ru>
Signed-off-by: NJohn W. Linville <linville@tuxdriver.com>

rfkill really should have been named rfswitch.  As it is, one can get
confused whether RFKILL_STATE_ON means the KILL switch is on (and
therefore, the radio is being *blocked* from operating), or whether it
means the RADIO rf output is on.

Clearly state that RFKILL_STATE_ON means the radio is *unblocked* from
operating (i.e. there is no rf killing going on).
Signed-off-by: NHenrique de Moraes Holschuh <hmh@hmh.eng.br>
Acked-by: NIvo van Doorn <IvDoorn@gmail.com>
Cc: Dmitry Torokhov <dtor@mail.ru>
Signed-off-by: NJohn W. Linville <linville@tuxdriver.com>

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: NIvo van Doorn <IvDoorn@gmail.com>
Acked-by: NDmitry Torokhov <dtor@mail.ru>
Acked-by: NRandy Dunlap <randy.dunlap@oracle.com>