Commit Graph

22 Commits

Author SHA1 Message Date
Mauro Carvalho Chehab
317a8455f1 rfkill.txt: standardize document format
Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:

- mark titles;
- comment contents index;
- mark literal blocks;
- adjust identation.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-07-14 13:58:02 -06:00
Mauro Carvalho Chehab
8c27ceff36 docs: fix locations of several documents that got moved
The previous patch renamed several files that are cross-referenced
along the Kernel documentation. Adjust the links to point to
the right places.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-10-24 08:12:35 -02:00
João Paulo Rechi Vita
50ee738d72 rfkill: Add documentation about LED triggers
Signed-off-by: João Paulo Rechi Vita <jprvita@endlessm.com>
Signed-off-by: Johannes Berg <johannes.berg@intel.com>
2016-02-24 09:13:12 +01:00
Andrew Clausen
0efbb786f1 rfkill: document rfkill module parameters
Document the rfkill module parameters default_state and
master_switch_mode.

Signed-off-by: Andrew Clausen <andrew.p.clausen@gmail.com>
[rewrite commit message]
Signed-off-by: Johannes Berg <johannes.berg@intel.com>
2015-01-09 23:22:12 +01:00
Carlos Garcia
c98be0c96d doc: spelling error changes
Fixed multiple spelling errors.

Acked-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Carlos E. Garcia <carlos@cgarcia.org>
Signed-off-by: Jiri Kosina <jkosina@suse.cz>
2014-05-05 15:32:05 +02:00
Xishi Qiu
c79a8d85d7 doc: fix some typos in documentations
Fix some typos in five documentations, no functional change.

Signed-off-by: Xishi Qiu <qiuxishi@huawei.com>
Acked-by: Rob Landley <rob@landley.net>
Signed-off-by: Jiri Kosina <jkosina@suse.cz>
2013-12-02 14:45:19 +01:00
Paul Bolle
395cf9691d doc: fix broken references
There are numerous broken references to Documentation files (in other
Documentation files, in comments, etc.). These broken references are
caused by typo's in the references, and by renames or removals of the
Documentation files. Some broken references are simply odd.

Fix these broken references, sometimes by dropping the irrelevant text
they were part of.

Signed-off-by: Paul Bolle <pebolle@tiscali.nl>
Signed-off-by: Jiri Kosina <jkosina@suse.cz>
2011-09-27 18:08:04 +02:00
florian@mickler.org
69c86373c6 Document the rfkill sysfs ABI
This moves sysfs ABI info from Documentation/rfkill.txt to the
ABI subfolder and reformats it.

This also schedules the deprecated sysfs parts to be removed in
2012 (claim file) and 2014 (state file).

Signed-off-by: Florian Mickler <florian@mickler.org>
Signed-off-by: John W. Linville <linville@tuxdriver.com>
2010-03-10 17:09:33 -05:00
Alan Jenkins
464902e812 rfkill: export persistent attribute in sysfs
This information allows userspace to implement a hybrid policy where
it can store the rfkill soft-blocked state in platform non-volatile
storage if available, and if not then file-based storage can be used.

Some users prefer platform non-volatile storage because of the behaviour
when dual-booting multiple versions of Linux, or if the rfkill setting
is changed in the BIOS setting screens, or if the BIOS responds to
wireless-toggle hotkeys itself before the relevant platform driver has
been loaded.

Signed-off-by: Alan Jenkins <alan-jenkins@tuffmail.co.uk>
Acked-by: Henrique de Moraes Holschuh <hmh@hmh.eng.br>
Signed-off-by: John W. Linville <linville@tuxdriver.com>
2009-06-19 11:50:18 -04:00
Johannes Berg
ce0879e324 rfkill: improve docs
Now that the dust has settled a bit, improve the docs on rfkill
and include more information about /dev/rfkill.

Signed-off-by: Johannes Berg <johannes@sipsolutions.net>
Signed-off-by: John W. Linville <linville@tuxdriver.com>
2009-06-15 15:05:58 -04:00
Johannes Berg
f71fea23a2 rfkill: document /dev/rfkill
Add some blurb about /dev/rfkill to the documentation and
fix the "transmiter" spelling error.

Signed-off-by: Johannes Berg <johannes@sipsolutions.net>
Signed-off-by: John W. Linville <linville@tuxdriver.com>
2009-06-03 14:06:15 -04:00
Johannes Berg
19d337dff9 rfkill: rewrite
This patch completely rewrites the rfkill core to address
the following deficiencies:

 * all rfkill drivers need to implement polling where necessary
   rather than having one central implementation

 * updating the rfkill state cannot be done from arbitrary
   contexts, forcing drivers to use schedule_work and requiring
   lots of code

 * rfkill drivers need to keep track of soft/hard blocked
   internally -- the core should do this

 * the rfkill API has many unexpected quirks, for example being
   asymmetric wrt. alloc/free and register/unregister

 * rfkill can call back into a driver from within a function the
   driver called -- this is prone to deadlocks and generally
   should be avoided

 * rfkill-input pointlessly is a separate module

 * drivers need to #ifdef rfkill functions (unless they want to
   depend on or select RFKILL) -- rfkill should provide inlines
   that do nothing if it isn't compiled in

 * the rfkill structure is not opaque -- drivers need to initialise
   it correctly (lots of sanity checking code required) -- instead
   force drivers to pass the right variables to rfkill_alloc()

 * the documentation is hard to read because it always assumes the
   reader is completely clueless and contains way TOO MANY CAPS

 * the rfkill code needlessly uses a lot of locks and atomic
   operations in locked sections

 * fix LED trigger to actually change the LED when the radio state
   changes -- this wasn't done before

Tested-by: Alan Jenkins <alan-jenkins@tuffmail.co.uk>
Signed-off-by: Henrique de Moraes Holschuh <hmh@hmh.eng.br> [thinkpad]
Signed-off-by: Johannes Berg <johannes@sipsolutions.net>
Signed-off-by: John W. Linville <linville@tuxdriver.com>
2009-06-03 14:06:13 -04:00
Johannes Berg
621cac8529 rfkill: remove user_claim stuff
Almost all drivers do not support user_claim, so remove it
completely and always report -EOPNOTSUPP to userspace. Since
userspace cannot really drive rfkill _anyway_ (due to the
odd restrictions imposed by the documentation) having this
code is just pointless.

Signed-off-by: Johannes Berg <johannes@sipsolutions.net>
Signed-off-by: John W. Linville <linville@tuxdriver.com>
2009-04-22 16:54:27 -04:00
Henrique de Moraes Holschuh
d003922dab rfkill: add master_switch_mode and EPO lock to rfkill and rfkill-input
Add of software-based sanity to rfkill and rfkill-input so that it can
reproduce what hardware-based EPO switches do, blocking all transmitters
and locking down any further attempts to unblock them until the switch is
deactivated.

rfkill-input is responsible for issuing the EPO control requests, like
before.

While an rfkill EPO is active, all transmitters are locked to one of the
BLOCKED states and all attempts to change that through the rfkill API
(userspace and kernel) will be either ignored or return -EPERM errors.

The lock will be released upon receipt of EV_SW SW_RFKILL_ALL ON by
rfkill-input, or should modular rfkill-input be unloaded.

This makes rfkill and rfkill-input extend the operation of an existing
wireless master kill switch to all wireless devices in the system, even
those that are not under hardware or firmware control.

Since the above is the expected operational behavior for the master rfkill
switch, the EPO lock functionality is not optional.

Also, extend rfkill-input to allow for three different behaviors when it
receives an EV_SW SW_RFKILL_ALL ON input event.  The user can set which
behavior he wants through the master_switch_mode parameter:

master_switch_mode = 0: EV_SW SW_RFKILL_ALL ON just unlocks rfkill
controller state changes (so that the rfkill userspace and kernel APIs can
now be used to change rfkill controller states again), but doesn't change
any of their states (so they will all remain blocked).  This is the safest
mode of operation, as it requires explicit operator action to re-enable a
transmitter.

master_switch_mode = 1: EV_SW SW_RFKILL_ALL ON causes rfkill-input to
attempt to restore the system to the state before the last EV_SW
SW_RFKILL_ALL OFF event, or to the default global states if no EV_SW
SW_RFKILL_ALL OFF ever happened.   This is the recommended mode of
operation for laptops.

master_switch_mode = 2: tries to unblock all rfkill controllers (i.e.
enable all transmitters) when an EV_SW SW_RFKILL_ALL ON event is received.
This is the default mode of operation, as it mimics the previous behavior
of rfkill-input.

In order to implement these features in a clean way, the entire event
handling of rfkill-input was refactored into a single worker function.

Protection against input event DoS (repeatedly firing rfkill events for
rfkill-input to process) was removed during the code refactoring.  It will
be added back in a future patch.

Note that with these changes, rfkill-input doesn't need to explicitly
handle any radio types for which KEY_<radio type> or SW_<radio type> events
do not exist yet.

Code to handle EV_SW SW_{WLAN,WWAN,BLUETOOTH,WIMAX,...} was added as it
might be needed in the future (and its implementation is not that obvious),
but is currently #ifdef'd out to avoid wasting resources.

Signed-off-by: Henrique de Moraes Holschuh <hmh@hmh.eng.br>
Cc: Ivo van Doorn <IvDoorn@gmail.com>
Cc: Dmitry Torokhov <dtor@mail.ru>
Signed-off-by: John W. Linville <linville@tuxdriver.com>
2008-10-31 19:00:09 -04:00
Henrique de Moraes Holschuh
bed7aac941 rfkill: remove transmitter blocking on suspend
Currently, rfkill would stand in the way of properly supporting wireless
devices that are capable of waking the system up from sleep or hibernation
when they receive a special wireless message.  It would also get in the way
of mesh devices that need to remain operational even during platform
suspend.

To avoid that, stop trying to block the transmitters on the rfkill class
suspend handler.

Drivers that need rfkill's older behaviour will have to implement it by
themselves in their own suspend handling.

Do note that rfkill *will* attempt to restore the transmitter state on
resume in any situation.  This happens after the driver's resume method is
called by the suspend core (class devices resume after the devices they are
attached to have been resumed).

The following drivers need to check if they need to explicitly block
their transmitters in their own suspend handlers (maintainers Cc'd):
	arch/arm/mach-pxa/tosa-bt.c
	drivers/net/usb/hso.c
	drivers/net/wireless/rt2x00/* (USB might need it?)
	drivers/net/wireless/b43/ (SSB over USB might need it?)
	drivers/misc/hp-wmi.c
	eeepc-laptop w/rfkill support (not in mainline yet)
	Compal laptop w/rfkill support (not in mainline yet)
	toshiba-acpi w/rfkill support (not in mainline yet)

Signed-off-by: Henrique de Moraes Holschuh <hmh@hmh.eng.br>
Cc: Ivo van Doorn <IvDoorn@gmail.com>
Cc: Matthew Garrett <mjg@redhat.com>
Cc: Andrew Bird <ajb@spheresystems.co.uk>
Cc: Greg Kroah-Hartman <gregkh@suse.de>
Cc: Cezary Jackiewicz <cezary.jackiewicz@gmail.com>
Cc: Philip Langdale <philipl@overt.org>
Signed-off-by: John W. Linville <linville@tuxdriver.com>
2008-09-15 16:48:25 -04:00
Henrique de Moraes Holschuh
e10e0dfe3b rfkill: protect suspended rfkill controllers
Guard rfkill controllers attached to a rfkill class against state changes
after class suspend has been issued.

Signed-off-by: Henrique de Moraes Holschuh <hmh@hmh.eng.br>
Acked-by: Ivo van Doorn <IvDoorn@gmail.com>
Signed-off-by: John W. Linville <linville@tuxdriver.com>
2008-08-18 11:05:12 -04:00
Henrique de Moraes Holschuh
2fd9b2212e rfkill: document rfkill_force_state as required (v2)
While the rfkill class does work with just get_state(), it doesn't work
well on devices that are subject to external events that cause rfkill state
changes.

Document that rfkill_force_state() is required in those cases.

Signed-off-by: Henrique de Moraes Holschuh <hmh@hmh.eng.br>
Acked-by: Ivo van Doorn <IvDoorn@gmail.com>
Signed-off-by: John W. Linville <linville@tuxdriver.com>
2008-07-29 16:36:32 -04:00
Henrique de Moraes Holschuh
f7983f7301 rfkill: improve documentation for kernel drivers
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: Henrique de Moraes Holschuh <hmh@hmh.eng.br>
Acked-by: Ivo van Doorn <IvDoorn@gmail.com>
Signed-off-by: John W. Linville <linville@tuxdriver.com>
2008-06-26 14:21:22 -04:00
Henrique de Moraes Holschuh
5005657cbd rfkill: rename the rfkill_state states and add block-locked state
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: Henrique de Moraes Holschuh <hmh@hmh.eng.br>
Acked-by: Ivo van Doorn <IvDoorn@gmail.com>
Signed-off-by: John W. Linville <linville@tuxdriver.com>
2008-06-26 14:21:22 -04:00
Henrique de Moraes Holschuh
dc288520a2 rfkill: document rw rfkill switches and clarify input subsystem interactions
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: Henrique de Moraes Holschuh <hmh@hmh.eng.br>
Acked-by: Ivo van Doorn <IvDoorn@gmail.com>
Cc: Dmitry Torokhov <dtor@mail.ru>
Signed-off-by: John W. Linville <linville@tuxdriver.com>
2008-06-26 14:21:22 -04:00
Henrique de Moraes Holschuh
f3146aff7f rfkill: clarify meaning of rfkill states
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: Henrique de Moraes Holschuh <hmh@hmh.eng.br>
Acked-by: Ivo van Doorn <IvDoorn@gmail.com>
Cc: Dmitry Torokhov <dtor@mail.ru>
Signed-off-by: John W. Linville <linville@tuxdriver.com>
2008-06-26 14:21:19 -04:00
Ivo van Doorn
dac24ab396 [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>
2007-10-10 16:49:24 -07:00