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>

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>
florian@mickler.org · John W. Linville
1 parent 75a9a92625
Showing 4 changed files with 102 additions and 31 deletions Side-by-side Diff
Documentation/ABI/obsolete/sysfs-class-rfkill
Documentation/ABI/stable/sysfs-class-rfkill
Documentation/feature-removal-schedule.txt
Documentation/rfkill.txt
+rfkill - radio frequency (RF) connector kill switch support
+
+For details to this subsystem look at Documentation/rfkill.txt.
+
+What:		/sys/class/rfkill/rfkill[0-9]+/state
+Date:		09-Jul-2007
+KernelVersion	v2.6.22
+Contact:	linux-wireless@vger.kernel.org
+Description: 	Current state of the transmitter.
+		This file is deprecated and sheduled to be removed in 2014,
+		because its not possible to express the 'soft and hard block'
+		state of the rfkill driver.
+Values: 	A numeric value.
+		0: RFKILL_STATE_SOFT_BLOCKED
+			transmitter is turned off by software
+		1: RFKILL_STATE_UNBLOCKED
+			transmitter is (potentially) active
+		2: RFKILL_STATE_HARD_BLOCKED
+			transmitter is forced off by something outside of
+			the driver's control.
+
+What:		/sys/class/rfkill/rfkill[0-9]+/claim
+Date:		09-Jul-2007
+KernelVersion	v2.6.22
+Contact:	linux-wireless@vger.kernel.org
+Description:	This file is deprecated because there no longer is a way to
+		claim just control over a single rfkill instance.
+		This file is scheduled to be removed in 2012.
+Values: 	0: Kernel handles events
+rfkill - radio frequency (RF) connector kill switch support
+
+For details to this subsystem look at Documentation/rfkill.txt.
+
+For the deprecated /sys/class/rfkill/*/state and
+/sys/class/rfkill/*/claim knobs of this interface look in
+Documentation/ABI/obsolte/sysfs-class-rfkill.
+
+What: 		/sys/class/rfkill
+Date:		09-Jul-2007
+KernelVersion:	v2.6.22
+Contact:	linux-wireless@vger.kernel.org,
+Description: 	The rfkill class subsystem folder.
+		Each registered rfkill driver is represented by an rfkillX
+		subfolder (X being an integer > 0).
+
+
+What:		/sys/class/rfkill/rfkill[0-9]+/name
+Date:		09-Jul-2007
+KernelVersion	v2.6.22
+Contact:	linux-wireless@vger.kernel.org
+Description: 	Name assigned by driver to this key (interface or driver name).
+Values: 	arbitrary string.
+
+
+What: 		/sys/class/rfkill/rfkill[0-9]+/type
+Date:		09-Jul-2007
+KernelVersion	v2.6.22
+Contact:	linux-wireless@vger.kernel.org
+Description: 	Driver type string ("wlan", "bluetooth", etc).
+Values: 	See include/linux/rfkill.h.
+
+
+What:		/sys/class/rfkill/rfkill[0-9]+/persistent
+Date:		09-Jul-2007
+KernelVersion	v2.6.22
+Contact:	linux-wireless@vger.kernel.org
+Description: 	Whether the soft blocked state is initialised from non-volatile
+		storage at startup.
+Values: 	A numeric value.
+		0: false
+		1: true
@@ -520,6 +520,24 @@
  
 ----------------------------
  
+What:	sysfs-class-rfkill state file
+When:	Feb 2014
+Files:	net/rfkill/core.c
+Why: 	Documented as obsolete since Feb 2010. This file is limited to 3
+	states while the rfkill drivers can have 4 states.
+Who: 	anybody or Florian Mickler <florian@mickler.org>
+
+----------------------------
+
+What: 	sysfs-class-rfkill claim file
+When:	Feb 2012
+Files:	net/rfkill/core.c
+Why:	It is not possible to claim an rfkill driver since 2007. This is
+	Documented as obsolete since Feb 2010.
+Who: 	anybody or Florian Mickler <florian@mickler.org>
+
+----------------------------
+
 What:	capifs
 When:	February 2011
 Files:	drivers/isdn/capi/capifs.*
@@ -99,42 +99,24 @@
 a specified type) into a state which also updates the default state for
 hotplugged devices.
  
-After an application opens /dev/rfkill, it can read the current state of
-all devices, and afterwards can poll the descriptor for hotplug or state
-change events.
+After an application opens /dev/rfkill, it can read the current state of all
+devices. Changes can be either obtained by either polling the descriptor for
+hotplug or state change events or by listening for uevents emitted by the
+rfkill core framework.
  
-Applications must ignore operations (the "op" field) they do not handle,
-this allows the API to be extended in the future.
+Additionally, each rfkill device is registered in sysfs and emits uevents.
  
-Additionally, each rfkill device is registered in sysfs and there has the
-following attributes:
+rfkill devices issue uevents (with an action of "change"), with the following
+environment variables set:
  
-	name: Name assigned by driver to this key (interface or driver name).
-	type: Driver type string ("wlan", "bluetooth", etc).
-	persistent: Whether the soft blocked state is initialised from
-	            non-volatile storage at startup.
-	state: Current state of the transmitter
-		0: RFKILL_STATE_SOFT_BLOCKED
-			transmitter is turned off by software
-		1: RFKILL_STATE_UNBLOCKED
-			transmitter is (potentially) active
-		2: RFKILL_STATE_HARD_BLOCKED
-			transmitter is forced off by something outside of
-			the driver's control.
-	       This file is deprecated because it can only properly show
-	       three of the four possible states, soft-and-hard-blocked is
-	       missing.
-	claim: 0: Kernel handles events
-	       This file is deprecated because there no longer is a way to
-	       claim just control over a single rfkill instance.
-
-rfkill devices also issue uevents (with an action of "change"), with the
-following environment variables set:
-
 RFKILL_NAME
 RFKILL_STATE
 RFKILL_TYPE
  
 The contents of these variables corresponds to the "name", "state" and
 "type" sysfs files explained above.
+
+
+For further details consult Documentation/ABI/stable/dev-rfkill and
+Documentation/ABI/stable/sysfs-class-rfkill.
	1	+rfkill - radio frequency (RF) connector kill switch support
	2	+
	3	+For details to this subsystem look at Documentation/rfkill.txt.
	4	+
	5	+What: /sys/class/rfkill/rfkill[0-9]+/state
	6	+Date: 09-Jul-2007
	7	+KernelVersion v2.6.22
	8	+Contact: linux-wireless@vger.kernel.org
	9	+Description: Current state of the transmitter.
	10	+ This file is deprecated and sheduled to be removed in 2014,
	11	+ because its not possible to express the 'soft and hard block'
	12	+ state of the rfkill driver.
	13	+Values: A numeric value.
	14	+ 0: RFKILL_STATE_SOFT_BLOCKED
	15	+ transmitter is turned off by software
	16	+ 1: RFKILL_STATE_UNBLOCKED
	17	+ transmitter is (potentially) active
	18	+ 2: RFKILL_STATE_HARD_BLOCKED
	19	+ transmitter is forced off by something outside of
	20	+ the driver's control.
	21	+
	22	+What: /sys/class/rfkill/rfkill[0-9]+/claim
	23	+Date: 09-Jul-2007
	24	+KernelVersion v2.6.22
	25	+Contact: linux-wireless@vger.kernel.org
	26	+Description: This file is deprecated because there no longer is a way to
	27	+ claim just control over a single rfkill instance.
	28	+ This file is scheduled to be removed in 2012.
	29	+Values: 0: Kernel handles events
	1	+rfkill - radio frequency (RF) connector kill switch support
	2	+
	3	+For details to this subsystem look at Documentation/rfkill.txt.
	4	+
	5	+For the deprecated /sys/class/rfkill/*/state and
	6	+/sys/class/rfkill/*/claim knobs of this interface look in
	7	+Documentation/ABI/obsolte/sysfs-class-rfkill.
	8	+
	9	+What: /sys/class/rfkill
	10	+Date: 09-Jul-2007
	11	+KernelVersion: v2.6.22
	12	+Contact: linux-wireless@vger.kernel.org,
	13	+Description: The rfkill class subsystem folder.
	14	+ Each registered rfkill driver is represented by an rfkillX
	15	+ subfolder (X being an integer > 0).
	16	+
	17	+
	18	+What: /sys/class/rfkill/rfkill[0-9]+/name
	19	+Date: 09-Jul-2007
	20	+KernelVersion v2.6.22
	21	+Contact: linux-wireless@vger.kernel.org
	22	+Description: Name assigned by driver to this key (interface or driver name).
	23	+Values: arbitrary string.
	24	+
	25	+
	26	+What: /sys/class/rfkill/rfkill[0-9]+/type
	27	+Date: 09-Jul-2007
	28	+KernelVersion v2.6.22
	29	+Contact: linux-wireless@vger.kernel.org
	30	+Description: Driver type string ("wlan", "bluetooth", etc).
	31	+Values: See include/linux/rfkill.h.
	32	+
	33	+
	34	+What: /sys/class/rfkill/rfkill[0-9]+/persistent
	35	+Date: 09-Jul-2007
	36	+KernelVersion v2.6.22
	37	+Contact: linux-wireless@vger.kernel.org
	38	+Description: Whether the soft blocked state is initialised from non-volatile
	39	+ storage at startup.
	40	+Values: A numeric value.
	41	+ 0: false
	42	+ 1: true
...	...	@@ -520,6 +520,24 @@
520	520
521	521	----------------------------
522	522
	523	+What: sysfs-class-rfkill state file
	524	+When: Feb 2014
	525	+Files: net/rfkill/core.c
	526	+Why: Documented as obsolete since Feb 2010. This file is limited to 3
	527	+ states while the rfkill drivers can have 4 states.
	528	+Who: anybody or Florian Mickler <florian@mickler.org>
	529	+
	530	+----------------------------
	531	+
	532	+What: sysfs-class-rfkill claim file
	533	+When: Feb 2012
	534	+Files: net/rfkill/core.c
	535	+Why: It is not possible to claim an rfkill driver since 2007. This is
	536	+ Documented as obsolete since Feb 2010.
	537	+Who: anybody or Florian Mickler <florian@mickler.org>
	538	+
	539	+----------------------------
	540	+
523	541	What: capifs
524	542	When: February 2011
525	543	Files: drivers/isdn/capi/capifs.*
...	...	@@ -99,42 +99,24 @@
99	99	a specified type) into a state which also updates the default state for
100	100	hotplugged devices.
101	101
102		-After an application opens /dev/rfkill, it can read the current state of
103		-all devices, and afterwards can poll the descriptor for hotplug or state
104		-change events.
	102	+After an application opens /dev/rfkill, it can read the current state of all
	103	+devices. Changes can be either obtained by either polling the descriptor for
	104	+hotplug or state change events or by listening for uevents emitted by the
	105	+rfkill core framework.
105	106
106		-Applications must ignore operations (the "op" field) they do not handle,
107		-this allows the API to be extended in the future.
	107	+Additionally, each rfkill device is registered in sysfs and emits uevents.
108	108
109		-Additionally, each rfkill device is registered in sysfs and there has the
110		-following attributes:
	109	+rfkill devices issue uevents (with an action of "change"), with the following
	110	+environment variables set:
111	111
112		- name: Name assigned by driver to this key (interface or driver name).
113		- type: Driver type string ("wlan", "bluetooth", etc).
114		- persistent: Whether the soft blocked state is initialised from
115		- non-volatile storage at startup.
116		- state: Current state of the transmitter
117		- 0: RFKILL_STATE_SOFT_BLOCKED
118		- transmitter is turned off by software
119		- 1: RFKILL_STATE_UNBLOCKED
120		- transmitter is (potentially) active
121		- 2: RFKILL_STATE_HARD_BLOCKED
122		- transmitter is forced off by something outside of
123		- the driver's control.
124		- This file is deprecated because it can only properly show
125		- three of the four possible states, soft-and-hard-blocked is
126		- missing.
127		- claim: 0: Kernel handles events
128		- This file is deprecated because there no longer is a way to
129		- claim just control over a single rfkill instance.
130		-
131		-rfkill devices also issue uevents (with an action of "change"), with the
132		-following environment variables set:
133		-
134	112	RFKILL_NAME
135	113	RFKILL_STATE
136	114	RFKILL_TYPE
137	115
138	116	The contents of these variables corresponds to the "name", "state" and
139	117	"type" sysfs files explained above.
	118	+
	119	+
	120	+For further details consult Documentation/ABI/stable/dev-rfkill and
	121	+Documentation/ABI/stable/sysfs-class-rfkill.