acer-wmi - Add documentation

Add some initial documentation detailing what acer-wmi is, and how to use it. Update the Kconfig entry with a reference to the documentation. Signed-off-by: Carlos Corbacho <carlos@strangeworlds.co.uk> Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Len Brown <len.brown@intel.com>

acer-wmi - Add documentation
Add some initial documentation detailing what acer-wmi is, and how to use it. Update the Kconfig entry with a reference to the documentation. Signed-off-by: Carlos Corbacho <carlos@strangeworlds.co.uk> Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Len Brown <len.brown@intel.com>
Carlos Corbacho · Len Brown
1 parent 018a651a9c
Showing 3 changed files with 207 additions and 0 deletions Side-by-side Diff
Documentation/laptops/00-INDEX
Documentation/laptops/acer-wmi.txt
drivers/misc/Kconfig
 00-INDEX
 	- This file
+acer-wmi.txt
+	- information on the Acer Laptop WMI Extras driver.
 sony-laptop.txt
 	- Sony Notebook Control Driver (SNC) Readme.
 sonypi.txt
+Acer Laptop WMI Extras Driver
+http://code.google.com/p/aceracpi
+Version 0.1
+9th February 2008
+
+Copyright 2007-2008 Carlos Corbacho <carlos@strangeworlds.co.uk>
+
+acer-wmi is a driver to allow you to control various parts of your Acer laptop
+hardware under Linux which are exposed via ACPI-WMI.
+
+This driver completely replaces the old out-of-tree acer_acpi, which I am
+currently maintaining for bug fixes only on pre-2.6.25 kernels. All development
+work is now focused solely on acer-wmi.
+
+Disclaimer
+**********
+
+Acer and Wistron have provided nothing towards the development acer_acpi or
+acer-wmi. All information we have has been through the efforts of the developers
+and the users to discover as much as possible about the hardware.
+
+As such, I do warn that this could break your hardware - this is extremely
+unlikely of course, but please bear this in mind.
+
+Background
+**********
+
+acer-wmi is derived from acer_acpi, originally developed by Mark
+Smith in 2005, then taken over by Carlos Corbacho in 2007, in order to activate
+the wireless LAN card under a 64-bit version of Linux, as acerhk[1] (the
+previous solution to the problem) relied on making 32 bit BIOS calls which are
+not possible in kernel space from a 64 bit OS.
+
+[1] acerhk: http://www.cakey.de/acerhk/
+
+Supported Hardware
+******************
+
+Please see the website for the current list of known working hardare:
+
+http://code.google.com/p/aceracpi/wiki/SupportedHardware
+
+If your laptop is not listed, or listed as unknown, and works with acer-wmi,
+please contact me with a copy of the DSDT.
+
+If your Acer laptop doesn't work with acer-wmi, I would also like to see the
+DSDT.
+
+To send me the DSDT, as root/sudo:
+
+cat /sys/firmware/acpi/DSDT > dsdt
+
+And send me the resulting 'dsdt' file.
+
+Usage
+*****
+
+On Acer laptops, acer-wmi should already be autoloaded based on DMI matching.
+For non-Acer laptops, until WMI based autoloading support is added, you will
+need to manually load acer-wmi.
+
+acer-wmi creates /sys/devices/platform/acer-wmi, and fills it with various
+files whose usage is detailed below, which enables you to control some of the
+following (varies between models):
+
+* the wireless LAN card radio
+* inbuilt Bluetooth adapter
+* inbuilt 3G card
+* mail LED of your laptop
+* brightness of the LCD panel
+
+Wireless
+********
+
+With regards to wireless, all acer-wmi does is enable the radio on the card. It
+is not responsible for the wireless LED - once the radio is enabled, this is
+down to the wireless driver for your card. So the behaviour of the wireless LED,
+once you enable the radio, will depend on your hardware and driver combination.
+
+e.g. With the BCM4318 on the Acer Aspire 5020 series:
+
+ndiswrapper: Light blinks on when transmitting
+bcm43xx/b43: Solid light, blinks off when transmitting
+
+Wireless radio control is unconditionally enabled - all Acer laptops that support
+acer-wmi come with built-in wireless. However, should you feel so inclined to
+ever wish to remove the card, or swap it out at some point, please get in touch
+with me, as we may well be able to gain some data on wireless card detection.
+
+To read the status of the wireless radio (0=off, 1=on):
+cat /sys/devices/platform/acer-wmi/wireless
+
+To enable the wireless radio:
+echo 1 > /sys/devices/platform/acer-wmi/wireless
+
+To disable the wireless radio:
+echo 0 > /sys/devices/platform/acer-wmi/wireless
+
+To set the state of the wireless radio when loading acer-wmi, pass:
+wireless=X (where X is 0 or 1)
+
+Bluetooth
+*********
+
+For bluetooth, this is an internal USB dongle, so once enabled, you will get
+a USB device connection event, and a new USB device appears. When you disable
+bluetooth, you get the reverse - a USB device disconnect event, followed by the
+device disappearing again.
+
+Bluetooth is autodetected by acer-wmi, so if you do not have a bluetooth module
+installed in your laptop, this file won't exist (please be aware that it is
+quite common for Acer not to fit bluetooth to their laptops - so just because
+you have a bluetooth button on the laptop, doesn't mean that bluetooth is
+installed).
+
+For the adventurously minded - if you want to buy an internal bluetooth
+module off the internet that is compatible with your laptop and fit it, then
+it will work just fine with acer-wmi.
+
+To read the status of the bluetooth module (0=off, 1=on):
+cat /sys/devices/platform/acer-wmi/wireless
+
+To enable the bluetooth module:
+echo 1 > /sys/devices/platform/acer-wmi/bluetooth
+
+To disable the bluetooth module:
+echo 0 > /sys/devices/platform/acer-wmi/bluetooth
+
+To set the state of the bluetooth module when loading acer-wmi, pass:
+bluetooth=X (where X is 0 or 1)
+
+3G
+**
+
+3G is currently not autodetected, so the 'threeg' file is always created under
+sysfs. So far, no-one in possession of an Acer laptop with 3G built-in appears to
+have tried Linux, or reported back, so we don't have any information on this.
+
+If you have an Acer laptop that does have a 3G card in, please contact me so we
+can properly detect these, and find out a bit more about them.
+
+To read the status of the 3G card (0=off, 1=on):
+cat /sys/devices/platform/acer-wmi/threeg
+
+To enable the 3G card:
+echo 1 > /sys/devices/platform/acer-wmi/threeg
+
+To disable the 3G card:
+echo 0 > /sys/devices/platform/acer-wmi/threeg
+
+To set the state of the 3G card when loading acer-wmi, pass:
+threeg=X (where X is 0 or 1)
+
+Mail LED
+********
+
+This can be found in most older Acer laptops supported by acer-wmi, and many
+newer ones - it is built into the 'mail' button, and blinks when active.
+
+On newer (WMID) laptops though, we have no way of detecting the mail LED. If
+your laptop identifies itself in dmesg as a WMID model, then please try loading
+acer_acpi with:
+
+force_series=2490
+
+This will use a known alternative method of reading/ writing the mail LED. If
+it works, please report back to me with the DMI data from your laptop so this
+can be added to acer-wmi.
+
+The LED is exposed through the LED subsystem, and can be found in:
+
+/sys/devices/platform/acer-wmi/leds/acer-mail:green/
+
+The mail LED is autodetected, so if you don't have one, the LED device won't
+be registered.
+
+If you have a mail LED that is not green, please report this to me.
+
+Backlight
+*********
+
+The backlight brightness control is available on all acer-wmi supported
+hardware. The maximum brightness level is usually 15, but on some newer laptops
+it's 10 (this is again autodetected).
+
+The backlight is exposed through the backlight subsystem, and can be found in:
+
+/sys/devices/platform/acer-wmi/backlight/acer-wmi/
+
+Credits
+*******
+
+Olaf Tauber, who did the real hard work when he developed acerhk
+http://www.informatik.hu-berlin.de/~tauber/acerhk
+All the authors of laptop ACPI modules in the kernel, whose work
+was an inspiration in the early days of acer_acpi
+Mathieu Segaud, who solved the problem with having to modprobe the driver
+twice in acer_acpi 0.2.
+Jim Ramsay, who added support for the WMID interface
+Mark Smith, who started the original acer_acpi
+
+And the many people who have used both acer_acpi and acer-wmi.
@@ -114,6 +114,9 @@
 	  wireless radio and bluetooth control, and on some laptops,
 	  exposes the mail LED and LCD backlight.
  
+	  For more information about this driver see
+	  <file:Documentation/laptops/acer-wmi.txt>
+
 	  If you have an ACPI-WMI compatible Acer/ Wistron laptop, say Y or M
 	  here.
1	1	00-INDEX
2	2	- This file
	3	+acer-wmi.txt
	4	+ - information on the Acer Laptop WMI Extras driver.
3	5	sony-laptop.txt
4	6	- Sony Notebook Control Driver (SNC) Readme.
5	7	sonypi.txt
	1	+Acer Laptop WMI Extras Driver
	2	+http://code.google.com/p/aceracpi
	3	+Version 0.1
	4	+9th February 2008
	5	+
	6	+Copyright 2007-2008 Carlos Corbacho <carlos@strangeworlds.co.uk>
	7	+
	8	+acer-wmi is a driver to allow you to control various parts of your Acer laptop
	9	+hardware under Linux which are exposed via ACPI-WMI.
	10	+
	11	+This driver completely replaces the old out-of-tree acer_acpi, which I am
	12	+currently maintaining for bug fixes only on pre-2.6.25 kernels. All development
	13	+work is now focused solely on acer-wmi.
	14	+
	15	+Disclaimer
	16	+**********
	17	+
	18	+Acer and Wistron have provided nothing towards the development acer_acpi or
	19	+acer-wmi. All information we have has been through the efforts of the developers
	20	+and the users to discover as much as possible about the hardware.
	21	+
	22	+As such, I do warn that this could break your hardware - this is extremely
	23	+unlikely of course, but please bear this in mind.
	24	+
	25	+Background
	26	+**********
	27	+
	28	+acer-wmi is derived from acer_acpi, originally developed by Mark
	29	+Smith in 2005, then taken over by Carlos Corbacho in 2007, in order to activate
	30	+the wireless LAN card under a 64-bit version of Linux, as acerhk[1] (the
	31	+previous solution to the problem) relied on making 32 bit BIOS calls which are
	32	+not possible in kernel space from a 64 bit OS.
	33	+
	34	+[1] acerhk: http://www.cakey.de/acerhk/
	35	+
	36	+Supported Hardware
	37	+******************
	38	+
	39	+Please see the website for the current list of known working hardare:
	40	+
	41	+http://code.google.com/p/aceracpi/wiki/SupportedHardware
	42	+
	43	+If your laptop is not listed, or listed as unknown, and works with acer-wmi,
	44	+please contact me with a copy of the DSDT.
	45	+
	46	+If your Acer laptop doesn't work with acer-wmi, I would also like to see the
	47	+DSDT.
	48	+
	49	+To send me the DSDT, as root/sudo:
	50	+
	51	+cat /sys/firmware/acpi/DSDT > dsdt
	52	+
	53	+And send me the resulting 'dsdt' file.
	54	+
	55	+Usage
	56	+*****
	57	+
	58	+On Acer laptops, acer-wmi should already be autoloaded based on DMI matching.
	59	+For non-Acer laptops, until WMI based autoloading support is added, you will
	60	+need to manually load acer-wmi.
	61	+
	62	+acer-wmi creates /sys/devices/platform/acer-wmi, and fills it with various
	63	+files whose usage is detailed below, which enables you to control some of the
	64	+following (varies between models):
	65	+
	66	+* the wireless LAN card radio
	67	+* inbuilt Bluetooth adapter
	68	+* inbuilt 3G card
	69	+* mail LED of your laptop
	70	+* brightness of the LCD panel
	71	+
	72	+Wireless
	73	+********
	74	+
	75	+With regards to wireless, all acer-wmi does is enable the radio on the card. It
	76	+is not responsible for the wireless LED - once the radio is enabled, this is
	77	+down to the wireless driver for your card. So the behaviour of the wireless LED,
	78	+once you enable the radio, will depend on your hardware and driver combination.
	79	+
	80	+e.g. With the BCM4318 on the Acer Aspire 5020 series:
	81	+
	82	+ndiswrapper: Light blinks on when transmitting
	83	+bcm43xx/b43: Solid light, blinks off when transmitting
	84	+
	85	+Wireless radio control is unconditionally enabled - all Acer laptops that support
	86	+acer-wmi come with built-in wireless. However, should you feel so inclined to
	87	+ever wish to remove the card, or swap it out at some point, please get in touch
	88	+with me, as we may well be able to gain some data on wireless card detection.
	89	+
	90	+To read the status of the wireless radio (0=off, 1=on):
	91	+cat /sys/devices/platform/acer-wmi/wireless
	92	+
	93	+To enable the wireless radio:
	94	+echo 1 > /sys/devices/platform/acer-wmi/wireless
	95	+
	96	+To disable the wireless radio:
	97	+echo 0 > /sys/devices/platform/acer-wmi/wireless
	98	+
	99	+To set the state of the wireless radio when loading acer-wmi, pass:
	100	+wireless=X (where X is 0 or 1)
	101	+
	102	+Bluetooth
	103	+*********
	104	+
	105	+For bluetooth, this is an internal USB dongle, so once enabled, you will get
	106	+a USB device connection event, and a new USB device appears. When you disable
	107	+bluetooth, you get the reverse - a USB device disconnect event, followed by the
	108	+device disappearing again.
	109	+
	110	+Bluetooth is autodetected by acer-wmi, so if you do not have a bluetooth module
	111	+installed in your laptop, this file won't exist (please be aware that it is
	112	+quite common for Acer not to fit bluetooth to their laptops - so just because
	113	+you have a bluetooth button on the laptop, doesn't mean that bluetooth is
	114	+installed).
	115	+
	116	+For the adventurously minded - if you want to buy an internal bluetooth
	117	+module off the internet that is compatible with your laptop and fit it, then
	118	+it will work just fine with acer-wmi.
	119	+
	120	+To read the status of the bluetooth module (0=off, 1=on):
	121	+cat /sys/devices/platform/acer-wmi/wireless
	122	+
	123	+To enable the bluetooth module:
	124	+echo 1 > /sys/devices/platform/acer-wmi/bluetooth
	125	+
	126	+To disable the bluetooth module:
	127	+echo 0 > /sys/devices/platform/acer-wmi/bluetooth
	128	+
	129	+To set the state of the bluetooth module when loading acer-wmi, pass:
	130	+bluetooth=X (where X is 0 or 1)
	131	+
	132	+3G
	133	+**
	134	+
	135	+3G is currently not autodetected, so the 'threeg' file is always created under
	136	+sysfs. So far, no-one in possession of an Acer laptop with 3G built-in appears to
	137	+have tried Linux, or reported back, so we don't have any information on this.
	138	+
	139	+If you have an Acer laptop that does have a 3G card in, please contact me so we
	140	+can properly detect these, and find out a bit more about them.
	141	+
	142	+To read the status of the 3G card (0=off, 1=on):
	143	+cat /sys/devices/platform/acer-wmi/threeg
	144	+
	145	+To enable the 3G card:
	146	+echo 1 > /sys/devices/platform/acer-wmi/threeg
	147	+
	148	+To disable the 3G card:
	149	+echo 0 > /sys/devices/platform/acer-wmi/threeg
	150	+
	151	+To set the state of the 3G card when loading acer-wmi, pass:
	152	+threeg=X (where X is 0 or 1)
	153	+
	154	+Mail LED
	155	+********
	156	+
	157	+This can be found in most older Acer laptops supported by acer-wmi, and many
	158	+newer ones - it is built into the 'mail' button, and blinks when active.
	159	+
	160	+On newer (WMID) laptops though, we have no way of detecting the mail LED. If
	161	+your laptop identifies itself in dmesg as a WMID model, then please try loading
	162	+acer_acpi with:
	163	+
	164	+force_series=2490
	165	+
	166	+This will use a known alternative method of reading/ writing the mail LED. If
	167	+it works, please report back to me with the DMI data from your laptop so this
	168	+can be added to acer-wmi.
	169	+
	170	+The LED is exposed through the LED subsystem, and can be found in:
	171	+
	172	+/sys/devices/platform/acer-wmi/leds/acer-mail:green/
	173	+
	174	+The mail LED is autodetected, so if you don't have one, the LED device won't
	175	+be registered.
	176	+
	177	+If you have a mail LED that is not green, please report this to me.
	178	+
	179	+Backlight
	180	+*********
	181	+
	182	+The backlight brightness control is available on all acer-wmi supported
	183	+hardware. The maximum brightness level is usually 15, but on some newer laptops
	184	+it's 10 (this is again autodetected).
	185	+
	186	+The backlight is exposed through the backlight subsystem, and can be found in:
	187	+
	188	+/sys/devices/platform/acer-wmi/backlight/acer-wmi/
	189	+
	190	+Credits
	191	+*******
	192	+
	193	+Olaf Tauber, who did the real hard work when he developed acerhk
	194	+http://www.informatik.hu-berlin.de/~tauber/acerhk
	195	+All the authors of laptop ACPI modules in the kernel, whose work
	196	+was an inspiration in the early days of acer_acpi
	197	+Mathieu Segaud, who solved the problem with having to modprobe the driver
	198	+twice in acer_acpi 0.2.
	199	+Jim Ramsay, who added support for the WMID interface
	200	+Mark Smith, who started the original acer_acpi
	201	+
	202	+And the many people who have used both acer_acpi and acer-wmi.
...	...	@@ -114,6 +114,9 @@
114	114	wireless radio and bluetooth control, and on some laptops,
115	115	exposes the mail LED and LCD backlight.
116	116
	117	+ For more information about this driver see
	118	+ <file:Documentation/laptops/acer-wmi.txt>
	119	+
117	120	If you have an ACPI-WMI compatible Acer/ Wistron laptop, say Y or M
118	121	here.
119	122