[linux.git] / Documentation / sonypi.txt

Sony Programmable I/O Control Device Driver Readme
--------------------------------------------------
	Copyright (C) 2001-2004 Stelian Pop <[email protected]>
	Copyright (C) 2001-2002 Alcôve <www.alcove.com>
	Copyright (C) 2001 Michael Ashley <[email protected]>
	Copyright (C) 2001 Junichi Morita <[email protected]>
	Copyright (C) 2000 Takaya Kinjo <[email protected]>
	Copyright (C) 2000 Andrew Tridgell <[email protected]>

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
				SONYPI_WIRELESS_MASK		0x2000

	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.

	- sonypi lacks the ability to distinguish between certain key
	  events on some models.

	- some models with the nvidia card (geforce go 6200 tc) uses a
	  different way to adjust the backlighting of the screen. There
	  is a userspace utility to adjust the brightness on those models,
	  which can be downloaded from
	  http://www.acc.umu.se/~erikw/program/smartdimmer-0.1.tar.bz2

	- since all development was done by reverse engineering, there is
	  _absolutely no guarantee_ that this driver will not crash your
	  laptop. Permanently.
Commit	Line	Data
1da177e4 LT	1	Sony Programmable I/O Control Device Driver Readme
	2	--------------------------------------------------
	3	Copyright (C) 2001-2004 Stelian Pop <[email protected]>
be2a608b	4	Copyright (C) 2001-2002 Alcôve <www.alcove.com>
1da177e4 LT	5	Copyright (C) 2001 Michael Ashley <[email protected]>
	6	Copyright (C) 2001 Junichi Morita <[email protected]>
	7	Copyright (C) 2000 Takaya Kinjo <[email protected]>
	8	Copyright (C) 2000 Andrew Tridgell <[email protected]>
	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
d2052c16	102	SONYPI_WIRELESS_MASK 0x2000
1da177e4 LT	103
	104	useinput: if set (which is the default) two input devices are
	105	created, one which interprets the jogdial events as
	106	mouse events, the other one which acts like a
	107	keyboard reporting the pressing of the special keys.
	108
	109	Module use:
	110	-----------
	111
	112	In order to automatically load the sonypi module on use, you can put those
	113	lines in your /etc/modprobe.conf file:
	114
	115	alias char-major-10-250 sonypi
	116	options sonypi minor=250
	117
	118	This supposes the use of minor 250 for the sonypi device:
	119
	120	# mknod /dev/sonypi c 10 250
	121
	122	Bugs:
	123	-----
	124
	125	- several users reported that this driver disables the BIOS-managed
	126	Fn-keys which put the laptop in sleeping state, or switch the
	127	external monitor on/off. There is no workaround yet, since this
	128	driver disables all APM management for those keys, by enabling the
	129	ACPI management (and the ACPI core stuff is not complete yet). If
	130	you have one of those laptops with working Fn keys and want to
	131	continue to use them, don't use this driver.
	132
	133	- some users reported that the laptop speed is lower (dhrystone
	134	tested) when using the driver with the fnkeyinit parameter. I cannot
	135	reproduce it on my laptop and not all users have this problem.
	136	This happens because the fnkeyinit parameter enables the ACPI
	137	mode (but without additional ACPI control, like processor
	138	speed handling etc). Use ACPI instead of APM if it works on your
	139	laptop.
	140
d2052c16 EW	141	- sonypi lacks the ability to distinguish between certain key
	142	events on some models.
	143
	144	- some models with the nvidia card (geforce go 6200 tc) uses a
	145	different way to adjust the backlighting of the screen. There
	146	is a userspace utility to adjust the brightness on those models,
	147	which can be downloaded from
	148	http://www.acc.umu.se/~erikw/program/smartdimmer-0.1.tar.bz2
	149
1da177e4 LT	150	- since all development was done by reverse engineering, there is
	151	_absolutely no guarantee_ that this driver will not crash your
	152	laptop. Permanently.