1 files changed, 142 insertions, 0 deletions
diff --git a/Documentation/sonypi.txt b/Documentation/sonypi.txt
new file mode 100644
index 000000000000..0f3b2405d09e
--- /dev/null
+++ b/Documentation/sonypi.txt
@@ -0,0 +1,142 @@
+Sony Programmable I/O Control Device Driver Readme
+--------------------------------------------------
+        Copyright (C) 2001-2004 Stelian Pop <stelian@popies.net>
+        Copyright (C) 2001-2002 Alcôve <www.alcove.com>
+        Copyright (C) 2001 Michael Ashley <m.ashley@unsw.edu.au>
+        Copyright (C) 2001 Junichi Morita <jun1m@mars.dti.ne.jp>
+        Copyright (C) 2000 Takaya Kinjo <t-kinjo@tc4.so-net.ne.jp>
+        Copyright (C) 2000 Andrew Tridgell <tridge@samba.org>
+This driver enables access to the Sony Programmable I/O Control Device which
+can be found in many Sony Vaio laptops. Some newer Sony laptops (seems to be
+limited to new FX series laptops, at least the FX501 and the FX702) lack a
+sonypi device and are not supported at all by this driver.
+It will give access (through a user space utility) to some events those laptops
+generate, like:
+        - jogdial events (the small wheel on the side of Vaios)
+        - capture button events (only on Vaio Picturebook series)
+        - Fn keys
+        - bluetooth button (only on C1VR model)
+        - programmable keys, back, help, zoom, thumbphrase buttons, etc.
+          (when available)
+Those events (see linux/sonypi.h) can be polled using the character device node
+/dev/sonypi (major 10, minor auto allocated or specified as a option).
+A simple daemon which translates the jogdial movements into mouse wheel events
+can be downloaded at: <http://popies.net/sonypi/>
+Another option to intercept the events is to get them directly through the
+input layer.
+This driver supports also some ioctl commands for setting the LCD screen
+brightness and querying the batteries charge information (some more
+commands may be added in the future).
+This driver can also be used to set the camera controls on Picturebook series
+(brightness, contrast etc), and is used by the video4linux driver for the
+Motion Eye camera.
+Please note that this driver was created by reverse engineering the Windows
+driver and the ACPI BIOS, because Sony doesn't agree to release any programming
+specs for its laptops. If someone convinces them to do so, drop me a note.
+Driver options:
+---------------
+Several options can be passed to the sonypi driver using the standard
+module argument syntax (<param>=<value> when passing the option to the
+module or sonypi.<param>=<value> on the kernel boot line when sonypi is
+statically linked into the kernel). Those options are:
+        minor:          minor number of the misc device /dev/sonypi,
+                        default is -1 (automatic allocation, see /proc/misc
+                        or kernel logs)
+        camera:         if you have a PictureBook series Vaio (with the
+                        integrated MotionEye camera), set this parameter to 1
+                        in order to let the driver access to the camera
+        fnkeyinit:      on some Vaios (C1VE, C1VR etc), the Fn key events don't
+                        get enabled unless you set this parameter to 1.
+                        Do not use this option unless it's actually necessary,
+                        some Vaio models don't deal well with this option.
+                        This option is available only if the kernel is
+                        compiled without ACPI support (since it conflicts
+                        with it and it shouldn't be required anyway if
+                        ACPI is already enabled).
+        verbose:        set to 1 to print unknown events received from the
+                        sonypi device.
+                        set to 2 to print all events received from the
+                        sonypi device.
+        compat:         uses some compatibility code for enabling the sonypi
+                        events. If the driver worked for you in the past
+                        (prior to version 1.5) and does not work anymore,
+                        add this option and report to the author.
+        mask:           event mask telling the driver what events will be
+                        reported to the user. This parameter is required for
+                        some Vaio models where the hardware reuses values
+                        used in other Vaio models (like the FX series who does
+                        not have a jogdial but reuses the jogdial events for
+                        programmable keys events). The default event mask is
+                        set to 0xffffffff, meaning that all possible events
+                        will be tried. You can use the following bits to
+                        construct your own event mask (from
+                        drivers/char/sonypi.h):
+                                SONYPI_JOGGER_MASK              0x0001
+                                SONYPI_CAPTURE_MASK             0x0002
+                                SONYPI_FNKEY_MASK               0x0004
+                                SONYPI_BLUETOOTH_MASK           0x0008
+                                SONYPI_PKEY_MASK                0x0010
+                                SONYPI_BACK_MASK                0x0020
+                                SONYPI_HELP_MASK                0x0040
+                                SONYPI_LID_MASK                 0x0080
+                                SONYPI_ZOOM_MASK                0x0100
+                                SONYPI_THUMBPHRASE_MASK         0x0200
+                                SONYPI_MEYE_MASK                0x0400
+                                SONYPI_MEMORYSTICK_MASK         0x0800
+                                SONYPI_BATTERY_MASK             0x1000
+        useinput:       if set (which is the default) two input devices are
+                        created, one which interprets the jogdial events as
+                        mouse events, the other one which acts like a
+                        keyboard reporting the pressing of the special keys.
+Module use:
+-----------
+In order to automatically load the sonypi module on use, you can put those
+lines in your /etc/modprobe.conf file:
+        alias char-major-10-250 sonypi
+        options sonypi minor=250
+This supposes the use of minor 250 for the sonypi device:
+        # mknod /dev/sonypi c 10 250
+Bugs:
+-----
+        - several users reported that this driver disables the BIOS-managed
+          Fn-keys which put the laptop in sleeping state, or switch the
+          external monitor on/off. There is no workaround yet, since this
+          driver disables all APM management for those keys, by enabling the
+          ACPI management (and the ACPI core stuff is not complete yet). If
+          you have one of those laptops with working Fn keys and want to
+          continue to use them, don't use this driver.
+        - some users reported that the laptop speed is lower (dhrystone
+          tested) when using the driver with the fnkeyinit parameter. I cannot
+          reproduce it on my laptop and not all users have this problem.
+          This happens because the fnkeyinit parameter enables the ACPI
+          mode (but without additional ACPI control, like processor
+          speed handling etc). Use ACPI instead of APM if it works on your
+          laptop.
+        - since all development was done by reverse engineering, there is
+          _absolutely no guarantee_ that this driver will not crash your
+          laptop. Permanently.

diff --git a/Documentation/sonypi.txt b/Documentation/sonypi.txt new file mode 100644 index 000000000000..0f3b2405d09e --- /dev/null +++ b/Documentation/sonypi.txt
@@ -0,0 +1,142 @@
	1	Sony Programmable I/O Control Device Driver Readme
	2	--------------------------------------------------
	3	Copyright (C) 2001-2004 Stelian Pop <stelian@popies.net>
	4	Copyright (C) 2001-2002 Alcôve <www.alcove.com>
	5	Copyright (C) 2001 Michael Ashley <m.ashley@unsw.edu.au>
	6	Copyright (C) 2001 Junichi Morita <jun1m@mars.dti.ne.jp>
	7	Copyright (C) 2000 Takaya Kinjo <t-kinjo@tc4.so-net.ne.jp>
	8	Copyright (C) 2000 Andrew Tridgell <tridge@samba.org>
	9
	10	This driver enables access to the Sony Programmable I/O Control Device which
	11	can be found in many Sony Vaio laptops. Some newer Sony laptops (seems to be
	12	limited to new FX series laptops, at least the FX501 and the FX702) lack a
	13	sonypi device and are not supported at all by this driver.
	14
	15	It will give access (through a user space utility) to some events those laptops
	16	generate, like:
	17	- jogdial events (the small wheel on the side of Vaios)
	18	- capture button events (only on Vaio Picturebook series)
	19	- Fn keys
	20	- bluetooth button (only on C1VR model)
	21	- programmable keys, back, help, zoom, thumbphrase buttons, etc.
	22	(when available)
	23
	24	Those events (see linux/sonypi.h) can be polled using the character device node
	25	/dev/sonypi (major 10, minor auto allocated or specified as a option).
	26	A simple daemon which translates the jogdial movements into mouse wheel events
	27	can be downloaded at: <http://popies.net/sonypi/>
	28
	29	Another option to intercept the events is to get them directly through the
	30	input layer.
	31
	32	This driver supports also some ioctl commands for setting the LCD screen
	33	brightness and querying the batteries charge information (some more
	34	commands may be added in the future).
	35
	36	This driver can also be used to set the camera controls on Picturebook series
	37	(brightness, contrast etc), and is used by the video4linux driver for the
	38	Motion Eye camera.
	39
	40	Please note that this driver was created by reverse engineering the Windows
	41	driver and the ACPI BIOS, because Sony doesn't agree to release any programming
	42	specs for its laptops. If someone convinces them to do so, drop me a note.
	43
	44	Driver options:
	45	---------------
	46
	47	Several options can be passed to the sonypi driver using the standard
	48	module argument syntax (<param>=<value> when passing the option to the
	49	module or sonypi.<param>=<value> on the kernel boot line when sonypi is
	50	statically linked into the kernel). Those options are:
	51
	52	minor: minor number of the misc device /dev/sonypi,
	53	default is -1 (automatic allocation, see /proc/misc
	54	or kernel logs)
	55
	56	camera: if you have a PictureBook series Vaio (with the
	57	integrated MotionEye camera), set this parameter to 1
	58	in order to let the driver access to the camera
	59
	60	fnkeyinit: on some Vaios (C1VE, C1VR etc), the Fn key events don't
	61	get enabled unless you set this parameter to 1.
	62	Do not use this option unless it's actually necessary,
	63	some Vaio models don't deal well with this option.
	64	This option is available only if the kernel is
	65	compiled without ACPI support (since it conflicts
	66	with it and it shouldn't be required anyway if
	67	ACPI is already enabled).
	68
	69	verbose: set to 1 to print unknown events received from the
	70	sonypi device.
	71	set to 2 to print all events received from the
	72	sonypi device.
	73
	74	compat: uses some compatibility code for enabling the sonypi
	75	events. If the driver worked for you in the past
	76	(prior to version 1.5) and does not work anymore,
	77	add this option and report to the author.
	78
	79	mask: event mask telling the driver what events will be
	80	reported to the user. This parameter is required for
	81	some Vaio models where the hardware reuses values
	82	used in other Vaio models (like the FX series who does
	83	not have a jogdial but reuses the jogdial events for
	84	programmable keys events). The default event mask is
	85	set to 0xffffffff, meaning that all possible events
	86	will be tried. You can use the following bits to
	87	construct your own event mask (from
	88	drivers/char/sonypi.h):
	89	SONYPI_JOGGER_MASK 0x0001
	90	SONYPI_CAPTURE_MASK 0x0002
	91	SONYPI_FNKEY_MASK 0x0004
	92	SONYPI_BLUETOOTH_MASK 0x0008
	93	SONYPI_PKEY_MASK 0x0010
	94	SONYPI_BACK_MASK 0x0020
	95	SONYPI_HELP_MASK 0x0040
	96	SONYPI_LID_MASK 0x0080
	97	SONYPI_ZOOM_MASK 0x0100
	98	SONYPI_THUMBPHRASE_MASK 0x0200
	99	SONYPI_MEYE_MASK 0x0400
	100	SONYPI_MEMORYSTICK_MASK 0x0800
	101	SONYPI_BATTERY_MASK 0x1000
	102
	103	useinput: if set (which is the default) two input devices are
	104	created, one which interprets the jogdial events as
	105	mouse events, the other one which acts like a
	106	keyboard reporting the pressing of the special keys.
	107
	108	Module use:
	109	-----------
	110
	111	In order to automatically load the sonypi module on use, you can put those
	112	lines in your /etc/modprobe.conf file:
	113
	114	alias char-major-10-250 sonypi
	115	options sonypi minor=250
	116
	117	This supposes the use of minor 250 for the sonypi device:
	118
	119	# mknod /dev/sonypi c 10 250
	120
	121	Bugs:
	122	-----
	123
	124	- several users reported that this driver disables the BIOS-managed
	125	Fn-keys which put the laptop in sleeping state, or switch the
	126	external monitor on/off. There is no workaround yet, since this
	127	driver disables all APM management for those keys, by enabling the
	128	ACPI management (and the ACPI core stuff is not complete yet). If
	129	you have one of those laptops with working Fn keys and want to
	130	continue to use them, don't use this driver.
	131
	132	- some users reported that the laptop speed is lower (dhrystone
	133	tested) when using the driver with the fnkeyinit parameter. I cannot
	134	reproduce it on my laptop and not all users have this problem.
	135	This happens because the fnkeyinit parameter enables the ACPI
	136	mode (but without additional ACPI control, like processor
	137	speed handling etc). Use ACPI instead of APM if it works on your
	138	laptop.
	139
	140	- since all development was done by reverse engineering, there is
	141	_absolutely no guarantee_ that this driver will not crash your
	142	laptop. Permanently.