sony-laptop: docs and maintainer update

From: Mattia Dongili <[email protected]>

Signed-off-by Mattia Dongili <[email protected]>

---
 MAINTAINERS |    2 ++
 1 files changed, 2 insertions(+), 0 deletions(-)

MAINTAINERS +0 -0

index efca26a..ec97723 100644

From: Mattia Dongili <[email protected]>

Be consistent with current implementation (backlight subsys and platform_device).

Signed-off-by Mattia Dongili <[email protected]>

---
 Documentation/acpi/sony_acpi.txt |   87 -------------------------------
 Documentation/sony-laptop.txt    |  106 ++++++++++++++++++++++++++++++++++++++
 drivers/misc/Kconfig             |   14 +++---
 3 files changed, 113 insertions(+), 94 deletions(-)

Documentation/acpi/sony_acpi.txt deleted +0 -87

deleted file mode 100644
index 35a04be..0000000
@@ -1,87 +0,0 @@
-ACPI Sony Notebook Control Driver (SNC) Readme
-----------------------------------------------
-	Copyright (C) 2004- 2005 Stelian Pop <[email protected]>
-
-This mini-driver drives the ACPI SNC device present in the
-ACPI BIOS of the Sony Vaio laptops.
-
-It gives access to some extra laptop functionalities. In
-its current form, this driver is mainly useful for controlling the
-screen brightness, but it may do more in the future.
-
-You should probably start by trying the sonypi driver, and try
-sony_acpi only if sonypi doesn't work for you.
-
-Usage:
-------
-
-Loading the sony_acpi module will create a /proc/acpi/sony/
-directory populated with a couple of files.
-
-You then read/write integer values from/to those files by using
-standard UNIX tools.
-
-The files are:
-	brightness		current screen brightness
-	brightness_default	screen brightness which will be set
-				when the laptop will be rebooted
-	cdpower			power on/off the internal CD drive
-
-Note that some files may be missing if they are not supported
-by your particular laptop model.
-
-Example usage:
-	# echo "1" > /proc/acpi/sony/brightness
-sets the lowest screen brightness,
-	# echo "8" > /proc/acpi/sony/brightness
-sets the highest screen brightness,
-	# cat /proc/acpi/sony/brightness
-retrieves the current screen brightness.
-
-Development:
-------------
-
-If you want to help with the development of this driver (and
-you are not afraid of any side effects doing strange things with
-your ACPI BIOS could have on your laptop), load the driver and
-pass the option 'debug=1'.
-
-REPEAT: DON'T DO THIS IF YOU DON'T LIKE RISKY BUSINESS.
-
-In your kernel logs you will find the list of all ACPI methods
-the SNC device has on your laptop. You can see the GBRT/SBRT methods
-used to get/set the brightness, but there are others.
-
-I HAVE NO IDEA WHAT THOSE METHODS DO.
-
-The sony_acpi driver creates, for some of those methods (the most
-current ones found on several Vaio models), an entry under
-/proc/acpi/sony/, just like the 'brightness' one. You can create
-other entries corresponding to your own laptop methods by further
-editing the source (see the 'sony_acpi_values' table, and add a new
-structure to this table with your get/set method names).
-
-Your mission, should you accept it, is to try finding out what
-those entries are for, by reading/writing random values from/to those
-files and find out what is the impact on your laptop.
-
-Should you find anything interesting, please report it back to me,
-I will not disavow all knowledge of your actions :)
-
-Bugs/Limitations:
------------------
-
-* This driver is not based on official documentation from Sony
-  (because there is none), so there is no guarantee this driver
-  will work at all, or do the right thing. Although this hasn't
-  happened to me, this driver could do very bad things to your
-  laptop, including permanent damage.
-
-* The sony_acpi and sonypi drivers do not interact at all. In the
-  future, sonypi could use sony_acpi to do (part of) its business.
-
-* spicctrl, which is the userspace tool used to communicate with the
-  sonypi driver (through /dev/sonypi) does not try to use the
-  sony_acpi driver. In the future, spicctrl could try sonypi first,
-  and if it isn't present, try sony_acpi instead.
-

Documentation/sony-laptop.txt new file +106 -0

new file mode 100644
index 0000000..dfd26df
@@ -0,0 +1,106 @@
+Sony Notebook Control Driver (SNC) Readme
+-----------------------------------------
+	Copyright (C) 2004- 2005 Stelian Pop <[email protected]>
+	Copyright (C) 2007 Mattia Dongili <[email protected]>
+
+This mini-driver drives the SNC device present in the ACPI BIOS of
+the Sony Vaio laptops.
+
+It gives access to some extra laptop functionalities. In its current
+form, this driver let the user set or query the screen brightness
+through the backlight subsystem and remove/apply power to some devices.
+
+Backlight control:
+------------------
+If your laptop model supports it, you will find sysfs files in the
+/sys/class/backlight/sony/
+directory. You will be able to query and set the current screen
+brightness:
+	brightness		get/set screen brightness (an iteger
+				between 0 and 7)
+	actual_brightness	reading from this file will query the HW
+				to get real brightness value
+	max_brightness		the maximum brightness value
+
+
+Platform specific:
+------------------
+Loading the sony-laptop module will create a
+/sys/devices/platform/sony-laptop/
+directory populated with some files.
+
+You then read/write integer values from/to those files by using
+standard UNIX tools.
+
+The files are:
+	brightness_default	screen brightness which will be set
+				when the laptop will be rebooted
+	cdpower			power on/off the internal CD drive
+	audiopower		power on/off the internal sound card
+	lanpower		power on/off the internal ethernet card
+				(only in debug mode)
+
+Note that some files may be missing if they are not supported
+by your particular laptop model.
+
+Example usage:
+	# echo "1" > /sys/devices/platform/sony-laptop/brightness_default
+sets the lowest screen brightness for the next and later reboots,
+	# echo "8" > /sys/devices/platform/sony-laptop/brightness_default
+sets the highest screen brightness for the next and later reboots,
+	# cat /sys/devices/platform/sony-laptop/brightness_default
+retrieves the value.
+
+	# echo "0" > /sys/devices/platform/sony-laptop/audiopower
+powers off the sound card,
+	# echo "1" > /sys/devices/platform/sony-laptop/audiopower
+powers on the sound card.
+
+Development:
+------------
+
+If you want to help with the development of this driver (and
+you are not afraid of any side effects doing strange things with
+your ACPI BIOS could have on your laptop), load the driver and
+pass the option 'debug=1'.
+
+REPEAT: DON'T DO THIS IF YOU DON'T LIKE RISKY BUSINESS.
+
+In your kernel logs you will find the list of all ACPI methods
+the SNC device has on your laptop. You can see the GCDP/GCDP methods
+used to pwer on/off the CD drive, but there are others.
+
+I HAVE NO IDEA WHAT THOSE METHODS DO.
+
+The sony-laptop driver creates, for some of those methods (the most
+current ones found on several Vaio models), an entry under
+/sys/devices/platform/sony-laptop, just like the 'cdpower' one.
+You can create other entries corresponding to your own laptop methods by
+further editing the source (see the 'sony_acpi_values' table, and add a new
+entry to this table with your get/set method names using the
+HANDLE_NAMES macro).
+
+Your mission, should you accept it, is to try finding out what
+those entries are for, by reading/writing random values from/to those
+files and find out what is the impact on your laptop.
+
+Should you find anything interesting, please report it back to me,
+I will not disavow all knowledge of your actions :)
+
+Bugs/Limitations:
+-----------------
+
+* This driver is not based on official documentation from Sony
+  (because there is none), so there is no guarantee this driver
+  will work at all, or do the right thing. Although this hasn't
+  happened to me, this driver could do very bad things to your
+  laptop, including permanent damage.
+
+* The sony-laptop and sonypi drivers do not interact at all. In the
+  future, sonypi could use sony-laptop to do (part of) its business.
+
+* spicctrl, which is the userspace tool used to communicate with the
+  sonypi driver (through /dev/sonypi) does not try to use the
+  sony-laptop driver. In the future, spicctrl could try sonypi first,
+  and if it isn't present, try sony-laptop instead.
+

drivers/misc/Kconfig +7 -7

index 926ae11..8c409dc 100644
@@ -112,14 +112,14 @@ config SONY_LAPTOP
 	depends on X86 && ACPI
 	select BACKLIGHT_CLASS_DEVICE
 	  ---help---
-	  This mini-driver drives the ACPI SNC device present in the
-	  ACPI BIOS of the Sony Vaio laptops.
+	  This mini-driver drives the SNC device present in the ACPI BIOS of
+	  the Sony Vaio laptops.
 
-	  It gives access to some extra laptop functionalities. In
-	  its current form, the only thing this driver does is letting
-	  the user set or query the screen brightness and remove/apply
-	  power to some devices.
+	  It gives access to some extra laptop functionalities. In its current
+	  form, this driver let the user set or query the screen brightness
+	  through the backlight subsystem and remove/apply power to some
+	  devices.
 
-	  Read <file:Documentation/acpi/sony_acpi.txt> for more information.
+	  Read <file:Documentation/sony-laptop.txt> for more information.
 
 endmenu

Quoted 7 lines · On Thursday 08 February 2007 14:16, [email protected] wrote:

From: Mattia Dongili <[email protected]>

Signed-off-by Mattia Dongili <[email protected]>

---
 MAINTAINERS |    2 ++
 1 files changed, 2 insertions(+), 0 deletions(-)

MAINTAINERS S: Maintained · line 3018

Quoted 12 lines

MAINTAINERS +2 -0

index efca26a..ec97723 100644
@@ -3012,6 +3012,8 @@ S:	Maintained
 SONY VAIO CONTROL DEVICE DRIVER
 P:	Stelian Pop
 M:	[email protected]
+P:	Mattia Dongili
+M:	[email protected]
 W:	http://popies.net/sonypi/
 S:	Maintained

Stelian, are you still actively maintaining Sony support,

or should we simply replace your name here with Mattia?

From what I recall, Mattia took over sony_acpi but didn't want to handle

Quoted 8 lines · Len Brown

Quoted 7 lines · On Thursday 08 February 2007 14:16, [email protected] wrote:

From: Mattia Dongili <[email protected]>

Signed-off-by Mattia Dongili <[email protected]>

---
 MAINTAINERS |    2 ++
 1 files changed, 2 insertions(+), 0 deletions(-)

Quoted 14 lines

MAINTAINERS S: Maintained · line 3018

Quoted 12 lines

MAINTAINERS +2 -0

index efca26a..ec97723 100644
@@ -3012,6 +3012,8 @@ S:	Maintained
 SONY VAIO CONTROL DEVICE DRIVER
 P:	Stelian Pop
 M:	[email protected]
+P:	Mattia Dongili
+M:	[email protected]
 W:	http://popies.net/sonypi/
 S:	Maintained

Stelian, are you still actively maintaining Sony support,

Actively definately not, though I still answer a lot of support questions about sonypi.

I even receive patches from time to time :)

Quoted 1 line

or should we simply replace your name here with Mattia?

Quoted 1 line

From what I recall, Mattia took over sony_acpi but didn't want to handle

sonypi as well, at least not for the time being.

If he changed his mind I'm hapily handing over the maintenance to him.

If not, maybe the MAINTAINERS entry should be clarified to say that Mattia maintains sony_acpi and sonypi is currently not maintained.

Quoted 34 lines · Stelian Pop

Quoted 8 lines · Len Brown

Quoted 7 lines · On Thursday 08 February 2007 14:16, [email protected] wrote:

From: Mattia Dongili <[email protected]>

Signed-off-by Mattia Dongili <[email protected]>

---
 MAINTAINERS |    2 ++
 1 files changed, 2 insertions(+), 0 deletions(-)

Quoted 14 lines

MAINTAINERS S: Maintained · line 3018

Quoted 12 lines

MAINTAINERS +2 -0

index efca26a..ec97723 100644
@@ -3012,6 +3012,8 @@ S:	Maintained
 SONY VAIO CONTROL DEVICE DRIVER
 P:	Stelian Pop
 M:	[email protected]
+P:	Mattia Dongili
+M:	[email protected]
 W:	http://popies.net/sonypi/
 S:	Maintained

Stelian, are you still actively maintaining Sony support,

Actively definately not, though I still answer a lot of support questions about sonypi.

I even receive patches from time to time :)

Quoted 3 lines

or should we simply replace your name here with Mattia?

From what I recall, Mattia took over sony_acpi but didn't want to handle

sonypi as well, at least not for the time being.

Quoted 4 lines

If he changed his mind I'm hapily handing over the maintenance to him.

If not, maybe the MAINTAINERS entry should be clarified to say that Mattia maintains sony_acpi and sonypi is currently not maintained.

Well, I'd hate losing possibly useful patches because the driver results unmaintained. :)
Sooo... updated MAINTAINERS patch will follow soon.

One question though: which subsystem should sonypi patches flow through?

On Friday 09 February 2007 09:01, Mattia Dongili wrote:

sonypi is an interesting beast, and I do mean beast. It pre-dates Linux ACPI support by several years and is chock-full of reverse engineered magic numbers.

It is much more complicated than sony-laptop.
It has a device file, ioctls, it registers for and handles irqs, it tickles bluetooth, the camera, the hotkeys, jog dial -- and it also registers with ACPI on SONY6001
and talks to the ACPI EC -- with or without ACPI present.

Presumably there is some application that talks to those ioctls.

Happily it already registers all the input events with the input layer.

I think one of the major decisions you need to make going forward is if it makes sense to maintain the parts of sonypi that are reverse engineered AML -- rather than simply running in ACPI mode and invoking the AML in the BIOS.

To be effective at this, you need a machine on hand that actually runs the sonypi features. Lacking that, you need active testers and a copy of their acpidump.

Personally, I think that invoking machine specific AML has its risks, but invoking C-ized machine specific AML sucked into a platform specific driver borders on the insane. (but Linux didn't have ACPI in 2000, so maybe "determined" would be a more appropriate word:-)

Stelian,
I think if you can list what you know actually works on what models, and what may not work, and what you think about the code needs to be changed, that would help Mattia enormously.

I suggest that the goal might be to have a single consolidated sony-laptop driver. Ie. port the working features one by one from sonypi into sony-laptop, and when sony-laptop can do everything that sonypi can do (though maybe not with the same ioctl interface etc) the schedule sonypi for deletion. But in the mean time, on the assumption the people actually use sonypi to make their vaio's dance in useful ways, I would leave it alone for their benefit.

Or, it may be possible to make a gradual transition -- this would spread the migration pain over a longer period, but would also spread the testing over a longer period and probably end up with a better driver in the end. You'd have to convince both drivers to load at the same time and to not conflict. Maybe some shared state could tell them which features are handled by which, so you could test if the new driver is working by flipping some load-time bits... I don't know if this is possible or not -- depends on how the features and the models interact with each other.

In any case, I think it would make sense to cook up a transition plan and to let the users know what you are thinking before you do it. If you don't have folks testing it on the models you don't have then you'll be unable to make progress.

Quoted 1 line

One question though: which subsystem should sonypi patches flow through?

In the interest of making ACPI use in the platform specific drivers sane and uniform, I'll be happy to be the conduit to upstream to clean this up. In particular, I'd really like to see the reverse engineered AML implemented as C IO reads and writes go away.

On Fri, Feb 09, 2007 at 11:58:18AM -0500, Len Brown wrote:

Quoted 6 lines

Quoted 1 line

One question though: which subsystem should sonypi patches flow through?

In the interest of making ACPI use in the platform specific drivers sane and uniform, I'll be happy to be the conduit to upstream to clean this up. In particular, I'd really like to see the reverse engineered AML implemented as C IO reads and writes go away.

sonypi is an interesting beast, and I do mean beast. It pre-dates Linux ACPI support by several years and is chock-full of reverse engineered magic numbers.

I think one of the major decisions you need to make going forward is if it makes sense to maintain the parts of sonypi that are reverse engineered AML -- rather than simply running in ACPI mode and invoking the AML in the BIOS.

Personally, I think that invoking machine specific AML has its risks, but invoking C-ized machine specific AML sucked into a platform specific driver borders on the insane. (but Linux didn't have ACPI in 2000, so maybe "determined" would be a more appropriate word:-)

Stelian,
I think if you can list what you know actually works on what models, and what may not work, and what you think about the code needs to be changed, that would help Mattia enormously.

I suggest that the goal might be to have a single consolidated sony-laptop driver. Ie. port the working features one by one from sonypi into sony-laptop, and when sony-laptop can do everything that sonypi can do (though maybe not with the same ioctl interface etc) the schedule sonypi for deletion. But in the mean time, on the assumption the people actually use sonypi to make their vaio's dance in useful ways, I would leave it alone for their benefit.

Quoted 1 line

Presumably there is some application that talks to those ioctls.

Yep, sonypid spicctrl sjog sonykeyd just to name a few.

Fortunately I own a type2 and a couple of type3 laptops but none of which has a motion eye camera.

At one point sonypi could just implement the ioctls and device file needed for backward compatibility.
But I need to start playing seriously with sonypi's code before getting a clear idea if this is really doable or not.

Stelian: thoughts?
I remember an (very?) old discussion where you've been asked to implement sonypi using acpi functions and the answer was something like "if acpi will allow that..."

Le vendredi 09 février 2007 à 11:58 -0500, Len Brown a écrit :

Quoted 4 lines

Stelian,
I think if you can list what you know actually works on what models, and what may not work, and what you think about the code needs to be changed, that would help Mattia enormously.

Unfortunately, this is something I always wanted to do and never get around to. I don't have such a list, I only have a rather big mail folder containing sony related mail.

I don't remember if I already said this, but I think it would be a good idea to start a wiki to create some sort of documentation.

Quoted 1 line · Stelian Pop

Le vendredi 09 février 2007 à 11:58 -0500, Len Brown a écrit :

[...]

Quoted 11 lines

Quoted 4 lines

Stelian,
I think if you can list what you know actually works on what models, and what may not work, and what you think about the code needs to be changed, that would help Mattia enormously.

Unfortunately, this is something I always wanted to do and never get around to. I don't have such a list, I only have a rather big mail folder containing sony related mail.

I don't remember if I already said this, but I think it would be a good idea to start a wiki to create some sort of documentation.

Yep, I'm (actually no me, some credit is due here) trying to setup a wiki to list such information. I'll post the address and maybe a call for help on some list to start growing the list.

Oh, Stelian: I'd also like to take a copy of you sonypi webpage there, would you allow that?