[PATCH 0/2] Document and enhance rfkill sysfs abi

[PATCH 0/2] Document and enhance rfkill sysfs abi

[florian]

Hi!

The first patch shuffles the sysfs-rfkill abi documentation into
Documentation/ABI. The second patch is more a "why not?" question in
patch-form. After stumbling over this arbitrary limitation of the rfkill*/state
in the Documentation.

Well.. why not?

Cheers,
Flo

Florian Mickler (2):
  Document the rfkill sysfs ABI
  enhance /sys/class/rfkill/<rfkill>/state interface

 Documentation/ABI/stable/sysfs-class-rfkill |   65 +++++++++++++++++++++++++++
 Documentation/rfkill.txt                    |   44 +++++-------------
 include/linux/rfkill.h                      |    3 +
 net/rfkill/core.c                           |    9 +++-
 4 files changed, 89 insertions(+), 32 deletions(-)
 create mode 100644 Documentation/ABI/stable/sysfs-class-rfkill

[PATCH 1/2] Document the rfkill sysfs ABI

[florian]

This moves sysfs ABI info from Documentation/rfkill.txt to the
ABI subfolder and reformats it.

Signed-off-by: Florian Mickler <florian@mickler.org>
---
 Documentation/ABI/stable/sysfs-class-rfkill |   64 +++++++++++++++++++++++++++
 Documentation/rfkill.txt                    |   44 +++++-------------
 2 files changed, 77 insertions(+), 31 deletions(-)
 create mode 100644 Documentation/ABI/stable/sysfs-class-rfkill

diff --git a/Documentation/ABI/stable/sysfs-class-rfkill b/Documentation/ABI/stable/sysfs-class-rfkill
new file mode 100644
index 0000000..53a4287
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-class-rfkill
@@ -0,0 +1,64 @@
+rfkill - radio frequency (RF) connector kill switch support
+
+For details to this subsystem look at Documentation/rfkill.txt.
+
+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
+
+
+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
+		because it can only properly show three of the four possible
+		states, soft-and-hard-blocked is missing.
+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.
+Values: 	0: Kernel handles events
diff --git a/Documentation/rfkill.txt b/Documentation/rfkill.txt
index b486050..83668e5 100644
--- a/Documentation/rfkill.txt
+++ b/Documentation/rfkill.txt
@@ -99,37 +99,15 @@ system. Also, it is possible to switch all rfkill drivers (or all drivers of
 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.
-
-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 there has the
-following attributes:
-
-	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:
+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.
+
+Additionally, each rfkill device is registered in sysfs and emits uevents.
+
+rfkill devices issue uevents (with an action of "change"), with the following
+environment variables set:
 
 RFKILL_NAME
 RFKILL_STATE
@@ -137,3 +115,7 @@ 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.6.6.1

Re: [PATCH 1/2] Document the rfkill sysfs ABI

[Johannes Berg]

On Sat, 2010-02-20 at 22:40 +0100, florian@mickler.org wrote:
> This moves sysfs ABI info from Documentation/rfkill.txt to the
> ABI subfolder and reformats it.
> 
> Signed-off-by: Florian Mickler <florian@mickler.org>

This is fine with me.

johannes

Re: [PATCH 1/2] Document the rfkill sysfs ABI

[Marcel Holtmann]

Hi Johannes,

> > This moves sysfs ABI info from Documentation/rfkill.txt to the
> > ABI subfolder and reformats it.
> > 
> > Signed-off-by: Florian Mickler <florian@mickler.org>
> 
> This is fine with me.

we have to be careful here. Some of these sysfs details needs to be
deprecated and removed. Applications should use /dev/rfkill actually.

Regards

Marcel

Re: [PATCH 1/2] Document the rfkill sysfs ABI

[Florian Mickler]

On Sun, 21 Feb 2010 11:08:50 +0100
Marcel Holtmann <marcel@holtmann.org> wrote:

> Hi Johannes,
> 
> > > This moves sysfs ABI info from Documentation/rfkill.txt to the
> > > ABI subfolder and reformats it.
> > > 
> > > Signed-off-by: Florian Mickler <florian@mickler.org>
> > 
> > This is fine with me.
> 
> we have to be careful here. Some of these sysfs details needs to be
> deprecated and removed. Applications should use /dev/rfkill actually.
> 
> Regards
> 
> Marcel
> 

There are three different categories: 
Documentation/ABI/stable 
Documentation/ABI/obsolete
Documentation/ABI/testing

Quoting from the ABI/README:
> The different levels of stability are:
> 
>   stable/
>         This directory documents the interfaces that the developer has
>         defined to be stable.  Userspace programs are free to use these
>         interfaces with no restrictions, and backward compatibility for
>         them will be guaranteed for at least 2 years.  Most interfaces
>         (like syscalls) are expected to never change and always be
>         available.
> 
>   testing/
>         This directory documents interfaces that are felt to be stable,
>         as the main development of this interface has been completed.
>         The interface can be changed to add new features, but the
>         current interface will not break by doing this, unless grave
>         errors or security problems are found in them.  Userspace
>         programs can start to rely on these interfaces, but they must be
>         aware of changes that can occur before these interfaces move to
>         be marked stable.  Programs that use these interfaces are
>         strongly encouraged to add their name to the description of
>         these interfaces, so that the kernel developers can easily
>         notify them if any changes occur (see the description of the
>         layout of the files below for details on how to do this.)
> 
>   obsolete/
>         This directory documents interfaces that are still remaining in
>         the kernel, but are marked to be removed at some later point in
>         time.  The description of the interface will document the reason
>         why it is obsolete and when it can be expected to be removed.
>         The file Documentation/feature-removal-schedule.txt may describe
>         some of these interfaces, giving a schedule for when they will
>         be removed.
> 
>   removed/
>         This directory contains a list of the old interfaces that have
>         been removed from the kernel.
> 


So the question is: are the state and claim file deprecated or obsolete? 
If they are considered obsolete I presume it would be ok, to put this
part of the ABI description into the obsolete/ subfolder. 

And should they be obsolete, should there be a new file ("blocked",
"state2.0",whatever,...) which exposes all possible states? I assume it
do be handy for scripted access to the rfkill device. 

cheers,
Flo

Re: [PATCH 1/2] Document the rfkill sysfs ABI

[John W. Linville]

On Sun, Feb 21, 2010 at 11:08:50AM +0100, Marcel Holtmann wrote:
> Hi Johannes,
> 
> > > This moves sysfs ABI info from Documentation/rfkill.txt to the
> > > ABI subfolder and reformats it.
> > > 
> > > Signed-off-by: Florian Mickler <florian@mickler.org>
> > 
> > This is fine with me.
> 
> we have to be careful here. Some of these sysfs details needs to be
> deprecated and removed. Applications should use /dev/rfkill actually.

Maybe all of it should be in "obsolete"?

-- 
John W. Linville		Someday the world will need a hero, and you
linville@tuxdriver.com			might be all we have.  Be ready.

Re: [PATCH 1/2] Document the rfkill sysfs ABI

[Johannes Berg]

[-- Attachment #1: Type: text/plain, Size: 837 bytes --]

On Mon, 2010-02-22 at 10:00 -0500, John W. Linville wrote:
> On Sun, Feb 21, 2010 at 11:08:50AM +0100, Marcel Holtmann wrote:
> > Hi Johannes,
> > 
> > > > This moves sysfs ABI info from Documentation/rfkill.txt to the
> > > > ABI subfolder and reformats it.
> > > > 
> > > > Signed-off-by: Florian Mickler <florian@mickler.org>
> > > 
> > > This is fine with me.
> > 
> > we have to be careful here. Some of these sysfs details needs to be
> > deprecated and removed. Applications should use /dev/rfkill
> actually.
> 
> Maybe all of it should be in "obsolete"?

Maybe, maybe not. Some people hate /dev/rfkill because it means they
need to use a programming language (rather than shell scripts), and I
don't care enough to fight with them.

For all I care, it can be at the current status quo forever.

johannes

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 801 bytes --]

Re: [PATCH 1/2] Document the rfkill sysfs ABI

[Marcel Holtmann]

Hi Johannes,

> > > > > This moves sysfs ABI info from Documentation/rfkill.txt to the
> > > > > ABI subfolder and reformats it.
> > > > > 
> > > > > Signed-off-by: Florian Mickler <florian@mickler.org>
> > > > 
> > > > This is fine with me.
> > > 
> > > we have to be careful here. Some of these sysfs details needs to be
> > > deprecated and removed. Applications should use /dev/rfkill
> > actually.
> > 
> > Maybe all of it should be in "obsolete"?
> 
> Maybe, maybe not. Some people hate /dev/rfkill because it means they
> need to use a programming language (rather than shell scripts), and I
> don't care enough to fight with them.
> 
> For all I care, it can be at the current status quo forever.

I am fine with having these information in sysfs, but then they should
be useful. So we should expose the hard and soft block states and not
some magic madeup state. Also the claim file has to go away.

And not that the rfkill utility is perfect for scripting, but
whatever ;)

Florian, feel free to export the details from /dev/rfkill as proper
sysfs attributes and make them ABI, then we can talk.

Regards

Marcel

[PATCH v2 0/2] Document and enhance rfkill sysfs abi

[florian]

Hi Marcel,

so this obsoletes the claim and state sysfs files and introduces two new files: 
/sys/class/rfkill/*/sw and hw .. 

cheers,
Flo

p.s.: i even tested them...

Florian Mickler (2):
  Document the rfkill sysfs ABI
  enhance sysfs rfkill interface

 Documentation/ABI/obsolete/sysfs-class-rfkill |   29 +++++++++++
 Documentation/ABI/stable/sysfs-class-rfkill   |   67 +++++++++++++++++++++++++
 Documentation/feature-removal-schedule.txt    |   18 +++++++
 Documentation/rfkill.txt                      |   44 +++++-----------
 net/rfkill/core.c                             |   57 +++++++++++++++++++++
 5 files changed, 184 insertions(+), 31 deletions(-)
 create mode 100644 Documentation/ABI/obsolete/sysfs-class-rfkill
 create mode 100644 Documentation/ABI/stable/sysfs-class-rfkill

[PATCH v2 1/2] Document the rfkill sysfs ABI

[florian]

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>
---
 Documentation/ABI/obsolete/sysfs-class-rfkill |   29 ++++++++++++++++
 Documentation/ABI/stable/sysfs-class-rfkill   |   42 +++++++++++++++++++++++
 Documentation/feature-removal-schedule.txt    |   18 ++++++++++
 Documentation/rfkill.txt                      |   44 +++++++-----------------
 4 files changed, 102 insertions(+), 31 deletions(-)
 create mode 100644 Documentation/ABI/obsolete/sysfs-class-rfkill
 create mode 100644 Documentation/ABI/stable/sysfs-class-rfkill

diff --git a/Documentation/ABI/obsolete/sysfs-class-rfkill b/Documentation/ABI/obsolete/sysfs-class-rfkill
new file mode 100644
index 0000000..ed7174e
--- /dev/null
+++ b/Documentation/ABI/obsolete/sysfs-class-rfkill
@@ -0,0 +1,29 @@
+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
diff --git a/Documentation/ABI/stable/sysfs-class-rfkill b/Documentation/ABI/stable/sysfs-class-rfkill
new file mode 100644
index 0000000..97d5064
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-class-rfkill
@@ -0,0 +1,42 @@
+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
diff --git a/Documentation/feature-removal-schedule.txt b/Documentation/feature-removal-schedule.txt
index 0a46833..b90c337 100644
--- a/Documentation/feature-removal-schedule.txt
+++ b/Documentation/feature-removal-schedule.txt
@@ -542,3 +542,21 @@ Why:	Duplicate functionality with the gspca_zc3xx driver, zc0301 only
 	sensors) wich are also supported by the gspca_zc3xx driver
 	(which supports 53 USB-ID's in total)
 Who:	Hans de Goede <hdegoede@redhat.com>
+
+----------------------------
+
+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>
diff --git a/Documentation/rfkill.txt b/Documentation/rfkill.txt
index b486050..83668e5 100644
--- a/Documentation/rfkill.txt
+++ b/Documentation/rfkill.txt
@@ -99,37 +99,15 @@ system. Also, it is possible to switch all rfkill drivers (or all drivers of
 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.
-
-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 there has the
-following attributes:
-
-	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:
+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.
+
+Additionally, each rfkill device is registered in sysfs and emits uevents.
+
+rfkill devices issue uevents (with an action of "change"), with the following
+environment variables set:
 
 RFKILL_NAME
 RFKILL_STATE
@@ -137,3 +115,7 @@ 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.6.6.1

[PATCH v2 2/2] enhance sysfs rfkill interface

[florian]

This commit introduces two new sysfs knobs.

/sys/class/rfkill/rfkill[0-9]+/hw: (ro)
	hardblock kill state
/sys/class/rfkill/rfkill[0-9]+/sw: (rw)
	softblock kill state

Signed-off-by: Florian Mickler <florian@mickler.org>
---

I am not shure about those names.
Other alternatives: 
[hs]w_block
block_[hs]w
block[sh]w
soft/hard

...


 Documentation/ABI/stable/sysfs-class-rfkill |   25 ++++++++++++
 net/rfkill/core.c                           |   57 +++++++++++++++++++++++++++
 2 files changed, 82 insertions(+), 0 deletions(-)

diff --git a/Documentation/ABI/stable/sysfs-class-rfkill b/Documentation/ABI/stable/sysfs-class-rfkill
index 97d5064..ccbbba2 100644
--- a/Documentation/ABI/stable/sysfs-class-rfkill
+++ b/Documentation/ABI/stable/sysfs-class-rfkill
@@ -40,3 +40,28 @@ Description: 	Whether the soft blocked state is initialised from non-volatile
 Values: 	A numeric value.
 		0: false
 		1: true
+
+
+What:		/sys/class/rfkill/rfkill[0-9]+/hw
+Date:		23-Feb-2010
+KernelVersion	v2.6.34
+Contact:	linux-wireless@vger.kernel.org
+Description: 	Current hardblock state. This file is read only.
+Values: 	A numeric value.
+		0: inactive
+			The transmitter is (potentially) active.
+		1: active
+			The transmitter is forced off by something outside of
+			the driver's control.
+
+
+What:		/sys/class/rfkill/rfkill[0-9]+/sw
+Date:		23-Feb-2010
+KernelVersion	v2.6.34
+Contact:	linux-wireless@vger.kernel.org
+Description:	Current softblock state. This file is read and write.
+Values: 	A numeric value.
+		0: inactive
+			The transmitter is (potentially) active.
+		1: active
+			The transmitter is turned off by software.
diff --git a/net/rfkill/core.c b/net/rfkill/core.c
index c218e07..b91e192 100644
--- a/net/rfkill/core.c
+++ b/net/rfkill/core.c
@@ -628,6 +628,61 @@ static ssize_t rfkill_persistent_show(struct device *dev,
 	return sprintf(buf, "%d\n", rfkill->persistent);
 }
 
+static ssize_t rfkill_hw_show(struct device *dev,
+				 struct device_attribute *attr,
+				 char *buf)
+{
+	struct rfkill *rfkill = to_rfkill(dev);
+	unsigned long flags;
+	u32 state;
+
+	spin_lock_irqsave(&rfkill->lock, flags);
+	state = rfkill->state;
+	spin_unlock_irqrestore(&rfkill->lock, flags);
+
+	return sprintf(buf, "%d\n", (state & RFKILL_BLOCK_HW) ? 1 : 0 );
+}
+
+static ssize_t rfkill_sw_show(struct device *dev,
+				 struct device_attribute *attr,
+				 char *buf)
+{
+	struct rfkill *rfkill = to_rfkill(dev);
+	unsigned long flags;
+	u32 state;
+
+	spin_lock_irqsave(&rfkill->lock, flags);
+	state = rfkill->state;
+	spin_unlock_irqrestore(&rfkill->lock, flags);
+
+	return sprintf(buf, "%d\n", (state & RFKILL_BLOCK_SW) ? 1 : 0 );
+}
+
+static ssize_t rfkill_sw_store(struct device *dev,
+				  struct device_attribute *attr,
+				  const char *buf, size_t count)
+{
+	struct rfkill *rfkill = to_rfkill(dev);
+	unsigned long state;
+	int err;
+
+	if (!capable(CAP_NET_ADMIN))
+		return -EPERM;
+
+	err = strict_strtoul(buf, 0, &state);
+	if (err)
+		return err;
+
+	if (state > 1 )
+		return -EINVAL;
+
+	mutex_lock(&rfkill_global_mutex);
+	rfkill_set_block(rfkill, state);
+	mutex_unlock(&rfkill_global_mutex);
+
+	return err ?: count;
+}
+
 static u8 user_state_from_blocked(unsigned long state)
 {
 	if (state & RFKILL_BLOCK_HW)
@@ -700,6 +755,8 @@ static struct device_attribute rfkill_dev_attrs[] = {
 	__ATTR(persistent, S_IRUGO, rfkill_persistent_show, NULL),
 	__ATTR(state, S_IRUGO|S_IWUSR, rfkill_state_show, rfkill_state_store),
 	__ATTR(claim, S_IRUGO|S_IWUSR, rfkill_claim_show, rfkill_claim_store),
+	__ATTR(sw, S_IRUGO|S_IWUSR, rfkill_sw_show, rfkill_sw_store),
+	__ATTR(hw, S_IRUGO, rfkill_hw_show, NULL),
 	__ATTR_NULL
 };
 
-- 
1.6.6.1

Re: [PATCH v2 2/2] enhance sysfs rfkill interface

[Henrique de Moraes Holschuh]

On Wed, 24 Feb 2010, florian@mickler.org wrote:
> /sys/class/rfkill/rfkill[0-9]+/hw: (ro)
> 	hardblock kill state
> /sys/class/rfkill/rfkill[0-9]+/sw: (rw)
> 	softblock kill state
> 
> Signed-off-by: Florian Mickler <florian@mickler.org>
> ---
> 
> I am not shure about those names.

I don't like them.  IMHO, you don't gain anything by being this terse, and
it is difficult to understand what they mean at first glance.

> Other alternatives: 
> [hs]w_block
> block_[hs]w

Any of those would be good, IMHO.  As would be more verbose variants like:
hardware_blocked, software_blocked, etc.

-- 
  "One disk to rule them all, One disk to find them. One disk to bring
  them all and in the darkness grind them. In the Land of Redmond
  where the shadows lie." -- The Silicon Valley Tarot
  Henrique Holschuh

Re: [PATCH v2 2/2] enhance sysfs rfkill interface

[florian]

Hi,

On Thu, 25 Feb 2010 20:35:16 -0300
Henrique de Moraes Holschuh <hmh@hmh.eng.br> wrote:

> On Wed, 24 Feb 2010, florian@mickler.org wrote:  
> > I am not shure about those names.  
> 
> I don't like them.  IMHO, you don't gain anything by being this terse, and
> it is difficult to understand what they mean at first glance.
>   
> > Other alternatives: 
> > [hs]w_block
> > block_[hs]w  
> 

I made that blocked_sw and blocked_hw, so that they are
lexicographically nearby and that they also give more information about
their content.

blocked_[hs]w -> 0/1 makes IMO kind of sense.

cheers,
Flo

[PATCH v3] enhance sysfs rfkill interface

[florian]

This commit introduces two new sysfs knobs.

/sys/class/rfkill/rfkill[0-9]+/blocked_hw: (ro)
	hardblock kill state
/sys/class/rfkill/rfkill[0-9]+/blocked_sw: (rw)
	softblock kill state

Signed-off-by: Florian Mickler <florian@mickler.org>
---
 Documentation/ABI/stable/sysfs-class-rfkill |   25 +++++++++++
 net/rfkill/core.c                           |   58 +++++++++++++++++++++++++++
 2 files changed, 83 insertions(+), 0 deletions(-)

this depends on the first patch: "[PATCH v2 1/2] Document the rfkill sysfs ABI"

diff --git a/Documentation/ABI/stable/sysfs-class-rfkill b/Documentation/ABI/stable/sysfs-class-rfkill
index 97d5064..b91c3f3 100644
--- a/Documentation/ABI/stable/sysfs-class-rfkill
+++ b/Documentation/ABI/stable/sysfs-class-rfkill
@@ -40,3 +40,28 @@ Description: 	Whether the soft blocked state is initialised from non-volatile
 Values: 	A numeric value.
 		0: false
 		1: true
+
+
+What:		/sys/class/rfkill/rfkill[0-9]+/blocked_hw
+Date:		23-Feb-2010
+KernelVersion	v2.6.34
+Contact:	linux-wireless@vger.kernel.org
+Description: 	Current hardblock state. This file is read only.
+Values: 	A numeric value.
+		0: inactive
+			The transmitter is (potentially) active.
+		1: active
+			The transmitter is forced off by something outside of
+			the driver's control.
+
+
+What:		/sys/class/rfkill/rfkill[0-9]+/blocked_sw
+Date:		23-Feb-2010
+KernelVersion	v2.6.34
+Contact:	linux-wireless@vger.kernel.org
+Description:	Current softblock state. This file is read and write.
+Values: 	A numeric value.
+		0: inactive
+			The transmitter is (potentially) active.
+		1: active
+			The transmitter is turned off by software.
diff --git a/net/rfkill/core.c b/net/rfkill/core.c
index c218e07..5f33151 100644
--- a/net/rfkill/core.c
+++ b/net/rfkill/core.c
@@ -628,6 +628,61 @@ static ssize_t rfkill_persistent_show(struct device *dev,
 	return sprintf(buf, "%d\n", rfkill->persistent);
 }
 
+static ssize_t rfkill_blocked_hw_show(struct device *dev,
+				 struct device_attribute *attr,
+				 char *buf)
+{
+	struct rfkill *rfkill = to_rfkill(dev);
+	unsigned long flags;
+	u32 state;
+
+	spin_lock_irqsave(&rfkill->lock, flags);
+	state = rfkill->state;
+	spin_unlock_irqrestore(&rfkill->lock, flags);
+
+	return sprintf(buf, "%d\n", (state & RFKILL_BLOCK_HW) ? 1 : 0 );
+}
+
+static ssize_t rfkill_blocked_sw_show(struct device *dev,
+				 struct device_attribute *attr,
+				 char *buf)
+{
+	struct rfkill *rfkill = to_rfkill(dev);
+	unsigned long flags;
+	u32 state;
+
+	spin_lock_irqsave(&rfkill->lock, flags);
+	state = rfkill->state;
+	spin_unlock_irqrestore(&rfkill->lock, flags);
+
+	return sprintf(buf, "%d\n", (state & RFKILL_BLOCK_SW) ? 1 : 0 );
+}
+
+static ssize_t rfkill_blocked_sw_store(struct device *dev,
+				  struct device_attribute *attr,
+				  const char *buf, size_t count)
+{
+	struct rfkill *rfkill = to_rfkill(dev);
+	unsigned long state;
+	int err;
+
+	if (!capable(CAP_NET_ADMIN))
+		return -EPERM;
+
+	err = strict_strtoul(buf, 0, &state);
+	if (err)
+		return err;
+
+	if (state > 1 )
+		return -EINVAL;
+
+	mutex_lock(&rfkill_global_mutex);
+	rfkill_set_block(rfkill, state);
+	mutex_unlock(&rfkill_global_mutex);
+
+	return err ?: count;
+}
+
 static u8 user_state_from_blocked(unsigned long state)
 {
 	if (state & RFKILL_BLOCK_HW)
@@ -700,6 +755,9 @@ static struct device_attribute rfkill_dev_attrs[] = {
 	__ATTR(persistent, S_IRUGO, rfkill_persistent_show, NULL),
 	__ATTR(state, S_IRUGO|S_IWUSR, rfkill_state_show, rfkill_state_store),
 	__ATTR(claim, S_IRUGO|S_IWUSR, rfkill_claim_show, rfkill_claim_store),
+	__ATTR(sw, S_IRUGO|S_IWUSR, rfkill_blocked_sw_show,
+			rfkill_blocked_sw_store),
+	__ATTR(hw, S_IRUGO, rfkill_blocked_hw_show, NULL),
 	__ATTR_NULL
 };
 
-- 
1.6.6.1

Re: [PATCH v2 2/2] enhance sysfs rfkill interface

[Marcel Holtmann]

Hi Florian,

> > > I am not shure about those names.  
> > 
> > I don't like them.  IMHO, you don't gain anything by being this terse, and
> > it is difficult to understand what they mean at first glance.
> >   
> > > Other alternatives: 
> > > [hs]w_block
> > > block_[hs]w  
> > 
> 
> I made that blocked_sw and blocked_hw, so that they are
> lexicographically nearby and that they also give more information about
> their content.
> 
> blocked_[hs]w -> 0/1 makes IMO kind of sense.

the kernel and /dev/rfkill just talks about "hard" and "soft" blocks.

Don't confuse this with hardware and software. It seems were are keeping
to make this stupid semantical error over and over again. So everything
that says hardware, software, hw or sw in the API is bluntly wrong.

Regards

Marcel

Re: [PATCH v2 2/2] enhance sysfs rfkill interface

[Florian Mickler]

On Fri, 26 Feb 2010 14:11:22 +0100
Marcel Holtmann <marcel@holtmann.org> wrote:

> Hi Florian,
> > blocked_[hs]w -> 0/1 makes IMO kind of sense.
> 
> the kernel and /dev/rfkill just talks about "hard" and "soft" blocks.
> 
> Don't confuse this with hardware and software. It seems were are keeping
> to make this stupid semantical error over and over again. So everything
> that says hardware, software, hw or sw in the API is bluntly wrong.
> 
> Regards
> 
> Marcel
> 

Yes, ok. I agree that 'hardware block' for something 'out of
the control of the driver' seems to be too narrow...

Alright. How about blocked_soft and blocked_hard?

cheers,
Flo

[PATCH 2/2] enhance /sys/class/rfkill/<rfkill>/state interface

[florian]

Introduce a new state-value RFKILL_STATE_SOFT_AND_HARD_BLOCKED
which is returned only through the sysfs state file.
The other interfaces are designed so that they don't need this extra
state.

This allows the sysfs to represent all possible states an rfkill driver can
have.

Signed-off-by: Florian Mickler <florian@mickler.org>
---

After stumbling over this arbitrary limitation of sys/class/rfkill/*/state I
wondered what would hinder this patch?

Documentation/ABI/stable/sysfs-class-rfkill |    7 ++++---
 include/linux/rfkill.h                      |    3 +++
 net/rfkill/core.c                           |    9 ++++++++-
 3 files changed, 15 insertions(+), 4 deletions(-)

diff --git a/Documentation/ABI/stable/sysfs-class-rfkill b/Documentation/ABI/stable/sysfs-class-rfkill
index 53a4287..0cda9b3 100644
--- a/Documentation/ABI/stable/sysfs-class-rfkill
+++ b/Documentation/ABI/stable/sysfs-class-rfkill
@@ -42,9 +42,7 @@ 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
-		because it can only properly show three of the four possible
-		states, soft-and-hard-blocked is missing.
+Description: 	Current state of the transmitter.
 Values: 	A numeric value.
 		0: RFKILL_STATE_SOFT_BLOCKED
 			transmitter is turned off by software
@@ -53,6 +51,9 @@ Values: 	A numeric value.
 		2: RFKILL_STATE_HARD_BLOCKED
 			transmitter is forced off by something outside of
 			the driver's control.
+		3: RFKILL_STATE_SOFT_AND_HARD_BLOCKED
+			transmitter is blocked by something outside of 
+			the driver's control as well as turned off by software
 
 
 What:		/sys/class/rfkill/rfkill[0-9]+/claim
diff --git a/include/linux/rfkill.h b/include/linux/rfkill.h
index 97059d0..b09a655 100644
--- a/include/linux/rfkill.h
+++ b/include/linux/rfkill.h
@@ -25,6 +25,8 @@
 #define RFKILL_STATE_SOFT_BLOCKED	0
 #define RFKILL_STATE_UNBLOCKED		1
 #define RFKILL_STATE_HARD_BLOCKED	2
+/* only used for sysfs */
+#define RFKILL_STATE_SOFT_AND_HARD_BLOCKED 3
 
 /**
  * enum rfkill_type - type of rfkill switch.
@@ -109,6 +111,7 @@ enum rfkill_user_states {
 	RFKILL_USER_STATE_SOFT_BLOCKED	= RFKILL_STATE_SOFT_BLOCKED,
 	RFKILL_USER_STATE_UNBLOCKED	= RFKILL_STATE_UNBLOCKED,
 	RFKILL_USER_STATE_HARD_BLOCKED	= RFKILL_STATE_HARD_BLOCKED,
+	RFKILL_USER_STATE_SOFT_AND_HARD_BLOCKED = RFKILL_STATE_SOFT_AND_HARD_BLOCKED,
 };
 #undef RFKILL_STATE_SOFT_BLOCKED
 #undef RFKILL_STATE_UNBLOCKED
diff --git a/net/rfkill/core.c b/net/rfkill/core.c
index c218e07..6d40297 100644
--- a/net/rfkill/core.c
+++ b/net/rfkill/core.c
@@ -645,12 +645,19 @@ static ssize_t rfkill_state_show(struct device *dev,
 	struct rfkill *rfkill = to_rfkill(dev);
 	unsigned long flags;
 	u32 state;
+	int user_state;
 
 	spin_lock_irqsave(&rfkill->lock, flags);
 	state = rfkill->state;
 	spin_unlock_irqrestore(&rfkill->lock, flags);
 
-	return sprintf(buf, "%d\n", user_state_from_blocked(state));
+	if (( state & RFKILL_BLOCK_HW ) && ( state & RFKILL_BLOCK_SW ))
+		user_state = RFKILL_USER_STATE_SOFT_AND_HARD_BLOCKED;
+	else
+		user_state = user_state_from_blocked(state);
+
+	return sprintf(buf, "%d\n", user_state);
+
 }
 
 static ssize_t rfkill_state_store(struct device *dev,
-- 
1.6.6.1

Re: [PATCH 2/2] enhance /sys/class/rfkill/<rfkill>/state interface

[Johannes Berg]

[-- Attachment #1: Type: text/plain, Size: 624 bytes --]

On Sat, 2010-02-20 at 22:40 +0100, florian@mickler.org wrote:
> Introduce a new state-value RFKILL_STATE_SOFT_AND_HARD_BLOCKED
> which is returned only through the sysfs state file.
> The other interfaces are designed so that they don't need this extra
> state.
> 
> This allows the sysfs to represent all possible states an rfkill
> driver can
> have.
> 
> Signed-off-by: Florian Mickler <florian@mickler.org>
> ---
> 
> After stumbling over this arbitrary limitation of
> sys/class/rfkill/*/state I
> wondered what would hinder this patch?

This is not backward compatible, so can't be done.

johannes

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 801 bytes --]

Re: [PATCH 2/2] enhance /sys/class/rfkill/<rfkill>/state interface

[Florian Mickler]

On Sat, 20 Feb 2010 23:14:48 +0100
Johannes Berg <johannes@sipsolutions.net> wrote:

> On Sat, 2010-02-20 at 22:40 +0100, florian@mickler.org wrote:
> > Introduce a new state-value RFKILL_STATE_SOFT_AND_HARD_BLOCKED
> > which is returned only through the sysfs state file.
> > The other interfaces are designed so that they don't need this extra
> > state.
> > 
> > This allows the sysfs to represent all possible states an rfkill
> > driver can
> > have.
> > 
> > Signed-off-by: Florian Mickler <florian@mickler.org>
> > ---
> > 
> > After stumbling over this arbitrary limitation of
> > sys/class/rfkill/*/state I
> > wondered what would hinder this patch?
> 
> This is not backward compatible, so can't be done.
> 
> johannes

hmm... ah, i see... if driver is in hard'n'soft-block state 
an userspace program would expect to read hardblock instead of the
new hard'n'softblock-state... 
now that i think of it, it even becomes obvious :) 

cheers,
Flo

Re: [PATCH 2/2] enhance /sys/class/rfkill/<rfkill>/state interface

[Marcel Holtmann]

Hi Florian,

> > > Introduce a new state-value RFKILL_STATE_SOFT_AND_HARD_BLOCKED
> > > which is returned only through the sysfs state file.
> > > The other interfaces are designed so that they don't need this extra
> > > state.
> > > 
> > > This allows the sysfs to represent all possible states an rfkill
> > > driver can
> > > have.
> > > 
> > > Signed-off-by: Florian Mickler <florian@mickler.org>
> > > ---
> > > 
> > > After stumbling over this arbitrary limitation of
> > > sys/class/rfkill/*/state I
> > > wondered what would hinder this patch?
> > 
> > This is not backward compatible, so can't be done.
> > 
> > johannes
> 
> hmm... ah, i see... if driver is in hard'n'soft-block state 
> an userspace program would expect to read hardblock instead of the
> new hard'n'softblock-state... 
> now that i think of it, it even becomes obvious :) 

a userspace program would be expected to use /dev/rfkill and do this
properly. Don't bother with sysfs at all.

Regards

Marcel

[PATCH 0/2] rfkill sysfs ABI

[florian]

Hi all!

The first patch moves the rfkill sysfs ABI Documentation to Documentation/ABI
and deprecates the state and claim file. 

The second patch creates a replacement for the state file. Instead of exporting
some made-up state we just export the state of the 2 kill lines. 

The first patch should probably go into 2.6.34, as to warn users 
(if there are any) early about this removal. 
If there is no intent to remove the broken files, the feature-removal-schedule hunk 
should probably be skipped. 

Cheers,
Flo

p.s.: first discussion of this: http://lkml.org/lkml/2010/2/22/127

Florian Mickler (2):
  Document the rfkill sysfs ABI
  enhance sysfs rfkill interface

 Documentation/ABI/obsolete/sysfs-class-rfkill |   29 +++++++++++
 Documentation/ABI/stable/sysfs-class-rfkill   |   67 +++++++++++++++++++++++++
 Documentation/feature-removal-schedule.txt    |   18 +++++++
 Documentation/rfkill.txt                      |   44 +++++-----------
 net/rfkill/core.c                             |   57 +++++++++++++++++++++
 5 files changed, 184 insertions(+), 31 deletions(-)
 create mode 100644 Documentation/ABI/obsolete/sysfs-class-rfkill
 create mode 100644 Documentation/ABI/stable/sysfs-class-rfkill

[PATCH 1/2] Document the rfkill sysfs ABI

[florian]

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>
---
 Documentation/ABI/obsolete/sysfs-class-rfkill |   29 ++++++++++++++++
 Documentation/ABI/stable/sysfs-class-rfkill   |   42 +++++++++++++++++++++++
 Documentation/feature-removal-schedule.txt    |   18 ++++++++++
 Documentation/rfkill.txt                      |   44 +++++++-----------------
 4 files changed, 102 insertions(+), 31 deletions(-)
 create mode 100644 Documentation/ABI/obsolete/sysfs-class-rfkill
 create mode 100644 Documentation/ABI/stable/sysfs-class-rfkill

diff --git a/Documentation/ABI/obsolete/sysfs-class-rfkill b/Documentation/ABI/obsolete/sysfs-class-rfkill
new file mode 100644
index 0000000..4201d5b
--- /dev/null
+++ b/Documentation/ABI/obsolete/sysfs-class-rfkill
@@ -0,0 +1,29 @@
+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
diff --git a/Documentation/ABI/stable/sysfs-class-rfkill b/Documentation/ABI/stable/sysfs-class-rfkill
new file mode 100644
index 0000000..3884344
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-class-rfkill
@@ -0,0 +1,42 @@
+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/obsolete/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
diff --git a/Documentation/feature-removal-schedule.txt b/Documentation/feature-removal-schedule.txt
index a5cc0db..9b450d7 100644
--- a/Documentation/feature-removal-schedule.txt
+++ b/Documentation/feature-removal-schedule.txt
@@ -520,6 +520,24 @@ Who:	Hans de Goede <hdegoede@redhat.com>
 
 ----------------------------
 
+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:	corgikbd, spitzkbd, tosakbd driver
 When:	2.6.35
 Files:	drivers/input/keyboard/{corgi,spitz,tosa}kbd.c
diff --git a/Documentation/rfkill.txt b/Documentation/rfkill.txt
index b486050..83668e5 100644
--- a/Documentation/rfkill.txt
+++ b/Documentation/rfkill.txt
@@ -99,37 +99,15 @@ system. Also, it is possible to switch all rfkill drivers (or all drivers of
 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.
-
-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 there has the
-following attributes:
-
-	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:
+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.
+
+Additionally, each rfkill device is registered in sysfs and emits uevents.
+
+rfkill devices issue uevents (with an action of "change"), with the following
+environment variables set:
 
 RFKILL_NAME
 RFKILL_STATE
@@ -137,3 +115,7 @@ 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.6.6.1