WMI patches for acpi-test (v2)

Len,

These patches replace the previous five you have in acpi-test - due to the changes to patch #2 (the sysfs support), and some other problems that turned up in some extra testing with it, I'd prefer if you replace the original patch series with this one.

Any further patches can then safely come as incremental ones on top of this series.

Also, two other things:

1) Would you be able to send me a copy of the DSDT for your Lenovo T61? I'd be interested to have a look at what Lenovo are doing with WMI.

2) Do you know of any IA64 systems using ACPI-WMI? At the moment, WMI will work on x86 and hopefully IA64, but if it turns out that no vendor has or ever will implement ACPI-WMI on IA64, then we could safely drop it there.

-Carlos

===

Patch #1: (WMI - driver and in kernel interface) - Minor clean up

* Delete 'default m' from Kconfig (as per your changes)
* Minor fix to MAINTAINERS (s/Supported/Maintained/ - oversight on my part)

====

Patch #2: (acer-wmi) - MAINTAINERS

* Add me to MAINTAINERS

====

Patch #3: (tc1100-wmi) - MAINTAINERS

* Add me to MAINTAINERS ('Odd Fixes' only, since I don't have the hardware)

RFC only, needs actual testing on the hardware, and probably very broken. Waiting on Matthew Garrett to get some free time to test this.

I'd ideally like someone to test this on the hardware before I drop the 'RFC' or am happy with this going upstream.

====

Patch #4: (WMI sysfs interface) - Various large fixups

* Merged with bus ID length patch (for future bisection purposes)

* Added new Kconfig option and ifdef's to make sysfs support optional (and try to make it clear that at the moment, it's a development & testing option only)

* Fixed various nasty bugs - crashes, memory leaks, etc (including one that prevented WMI unloading if sysfs support was enabled)

* Drop the RFC

====

Patch #5: (WMI documentation) - New

Some simple documentation of the in kernel and sysfs (userspace) WMI interface.

Len:

'data' is a binary file, since WMI provides no information on what is returned by any given WMI method/ data block, so we don't try and do anything with it - just return whatever the ACPI buffer contains. You also need to set 'instance' first.

To do anything useful with the sysfs interface, you'll probably need something that can:

A) Set 'instance'
B) Read 'data' for the given GUID
C) Knows what is being returned
D) Can turn that into something useful to output back

In MS land, (C) is usually provided by a MOF file - since we tend not to have these available, the only alternative is to look at the DSDT and work out what size structure you need to hold the returned data.
---

Carlos Corbacho (5):
ACPI: WMI: Add documentation
ACPI: WMI: Add sysfs userspace interface
[RFC] tc1100-wmi: Add driver for HP Compaq TC1100 Tablets
acer-wmi: Add driver for newer Acer laptops
ACPI: WMI: Add ACPI-WMI mapping driver

 Documentation/acpi/wmi.txt |  131 +++++
 MAINTAINERS                |   19 +
 drivers/acpi/Kconfig       |   20 +
 drivers/acpi/Makefile      |    1 
 drivers/acpi/wmi.c         | 1253 ++++++++++++++++++++++++++++++++++++++++++++
 drivers/misc/Kconfig       |   25 +
 drivers/misc/Makefile      |    2 
 drivers/misc/acer-wmi.c    | 1109 +++++++++++++++++++++++++++++++++++++++
 drivers/misc/tc1100-wmi.c  |  290 ++++++++++
 include/linux/acpi.h       |   21 +
 10 files changed, 2871 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/acpi/wmi.txt
 create mode 100644 drivers/acpi/wmi.c
 create mode 100644 drivers/misc/acer-wmi.c
 create mode 100644 drivers/misc/tc1100-wmi.c

Add documentation for WMI-ACPI, giving basic information for WMI driver and userspace writers.

===
ChangeLog

v1 (2007-11-28)

Initial version

v2 (2007-12-08)

Update with latest changes to sysfs interface

v3 (2008-02-05)

Update
---

 Documentation/acpi/wmi.txt |  131 ++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 131 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/acpi/wmi.txt

new file mode 100644
index 0000000..4d243aa
@@ -0,0 +1,131 @@
+ACPI-WMI mapping driver
+
+Copyright (C) 2007-2008 Carlos Corbacho <[email protected]>
+
+Updated: 5th February 2008
+
+1) About this guide
+
+This guide is a basic introduction on how to interact with the ACPI-WMI mapper
+driver in the kernel - it presumes you already have a basic knowledge of
+ACPI-WMI, ACPI and the hardware you are writing the driver for.
+
+2) What is ACPI-WMI
+
+At its simplest, ACPI-WMI is a proprietary extension to the ACPI specification
+from Microsoft to allow WMI (their implementation of WBEM) to access
+instrumentation data and methods in ACPI from userspace, via the ACPI _HID
+device PNP0C14.
+
+3) What is the ACPI-WMI mapper
+
+The Linux ACPI-WMI driver is the implementation of this mapper for Linux.
+
+NOTE: The mapper does not do anything itself with the ACPI-WMI devices - it
+simply makes their functionality available to other drivers and userspace.
+
+4) Implementation
+
+A general note:
+
+ACPI-WMI has no knowledge of the size of the data blocks passed to/ from
+ACPI-WMI - this is not encoded in the DSDT, and is usually only available in
+the form of a MOF file. If this is not available, you will need to analyze
+the DSDT to get this information.
+
+You will therefore need to know in advance the size of any data structures
+to handle them.
+
+Userspace:
+
+ACPI-WMI is exposed to userspace via sysfs and netlink. Data and methods are
+exposed through sysfs, events are sent via netlink.
+
+Accessing ACPI-WMI directly through sysfs is generally not recommended -
+ideally, this should be done by a userspace library, which could also deal
+with the netlink events.
+
+The sysfs interface is in /sys/devices/virtual/wmi for WMI methods and data, as
+follows:
+
+/sys/devices/virtual/wmi/
+|
+|-> <GUID>/
+ |-> type (method, data, event)
+
+Method & data blocks
+ |-> instance (instance to execute)
+ |-> instance_count (read only - maximum number of instances available)
+ |-> data (binary data file - write input data to file, read file
+           to execute method and/ or retrieve data).
+
+To read/ write a data block, instance must be set first.
+
+Method only
+ |-> method_id (write value of method id to execute)
+
+To execute a method, instance and method_id must be set first.
+
+Events - passed to userspace via netlink. However, the extra WMI data
+associated with an event is exposed through sysfs.
+
+ |-> notification (ACPI event value)
+ |-> data (binary data file - WMI data associated with the event)
+
+Kernel interface:
+
+For drivers that want to bypass userspace (either because WBEM is overkill,
+or a userspace application is not really appropriate for want you want to do),
+and talk directly to ACPI-WMI, then the mapper also exports functions
+to do this - these are essentially thin wrappers around ACPI, so if you are
+familiar with writing an ACPI driver, then writing a WMI driver is not much more
+of a stretch.
+
+The exported ACPI-WMI functions can be found in <linux/acpi.h>
+
+The most important differences between ACPI and WMI drivers are:
+
+A) WMI based drivers should be platform drivers, not ACPI drivers.
+
+B) ACPI details such as handles and/ or path names are hidden; you use GUIDs as
+   the unique identifier to call methods instead (you don't need to care either
+   about multiple PNP0C14 devices existing - the GUIDs are always unique, and
+   these are what you will work with).
+
+C) In your probe() function, you should use wmi_has_guid() to look for the
+   GUID(s) you need for your driver.
+
+For the in kernel interface, the following functions are available:
+
+wmi_evaluate_method():
+
+Evaluate a WMI method.
+
+wmi_query_block():
+
+Return the contents of a WMI data block.
+
+wmi_set_block()
+
+Set the contents of a WMI data block.
+
+wmi_install_notify_handler():
+wmi_remove_notify_handler():
+
+Install and/ or remove a handler for a WMI event - one handler per GUID.
+
+wmi_get_event_data():
+
+Return the data associated with a given WMI event.
+
+wmi_has_guid():
+
+Returns true if a given GUID is available on the system.
+
+wmi_get_device():
+
+Return a pointer to the virtual device associated with a GUID. If you need to
+set a parent device (e.g. for an input device), use this.
+
+
+[1] http://www.microsoft.com/whdc/system/pnppwr/wmi/wmi-acpi.mspx

The following is an implementation of the Windows Management Instrumentation (WMI) ACPI interface mapper (PNP0C14).

What it does:

Parses the _WDG method and exports functions to process WMI method calls, data block query/ set commands (both based on GUID) and does basic event handling.

How: WMI presents an in kernel interface here (essentially, a minimal wrapper around ACPI)

(const char *guid assume the 36 character ASCII representation of a GUID - e.g. 67C3371D-95A3-4C37-BB61-DD47B491DAAB)

wmi_evaluate_method(const char *guid, u8 instance, u32 method_id, const struct acpi_buffer *in, struct acpi_buffer *out)

wmi_query_block(const char *guid, u8 instance,
struct acpi_buffer *out)

wmi_set_block(const char *guid, u38 instance,
const struct acpi_buffer *in)

wmi_install_notify_handler(acpi_notify_handler handler);

wmi_remove_notify_handler(void);

wmi_get_event_data(u32 event, struct acpi_buffer *out)

wmi_has_guid(const char guid*)

wmi_has_guid() is a helper function to find if a GUID exists or not on the system (a quick and easy way for WMI dependant drivers to see if the the method/ block they want exists, since GUIDs are supposed to be unique).

Event handling - allow a WMI based driver to register a notifier handler for each GUID with WMI. When a notification is sent to a GUID in WMI, the handler registered with WMI is then called (it is left to the caller to ask for the WMI event data associated with the GUID, if needed).

What it won't do:

Unicode - The MS article[1] calls for converting between ASCII and Unicode (or vice versa) if a GUID is marked as "string". This is left up to the calling driver.

Handle a MOF[1] - the WMI mapper just exports methods, data and events to userspace. MOF handling is down to userspace.

Userspace interface - this will be added later.

[1] http://www.microsoft.com/whdc/system/pnppwr/wmi/wmi-acpi.mspx

===
ChangeLog
==

v1 (2007-10-02):

* Initial release

v2 (2007-10-05):

* Cleaned up code - split up super "wmi_evaluate_block" -> each external symbol now handles its own ACPI calls, rather than handing off to a "super" method (and in turn, is a lot simpler to read)
* Added a find_guid() symbol - return true if a given GUID exists on the system
* wmi_* functions now return type acpi_status (since they are just fancy wrappers around acpi_evaluate_object())
* Removed extra debug code

v3 (2007-10-27)

* More code clean up - now passes checkpatch.pl
* Change data block calls - ref MS spec, method ID is not required for them, so drop it from the function parameters.
* Const'ify guid in the function call parameters.
* Fix _WDG buffer handling - copy the data to our own private structure.
* Change WMI from tristate to bool - otherwise the external functions are not exported in linux/acpi.h if you try to build WMI as a module.
* Fix more flag comparisons.
* Add a maintainers entry - since I wrote this, I should take the blame for it.

v4 (2007-10-30)

* Add missing brace from after fixing checkpatch errors.
* Rewrote event handling - allow external drivers to register with WMI to handle WMI events
* Clean up flags and sanitise flag handling

v5 (2007-11-03)

* Add sysfs interface for userspace. Export events over netlink again.
* Remove module left overs, fully convert to built-in driver.
* Tweak in-kernel API to use u8 for instance, since this is what the GUID blocks use (so instance cannot be greater than u8).
* Export wmi_get_event_data() for in kernel WMI drivers.

v6 (2007-11-07)

* Split out userspace into a different patch

v7 (2007-11-20)

* Fix driver to handle multiple PNP0C14 devices - store all GUIDs using the kernel's built in list functions, and just keep adding to the list every time we handle a PNP0C14 devices - GUIDs will always be unique, and WMI callers do not know or care about different devices.
* Change WMI event handler registration to use its' own event handling struct; we should not pass an acpi_handle down to any WMI based drivers
- they should be able to function with only the calls provided in WMI.
* Update my e-mail address

v8 (2007-11-28)

* Convert back to a module.
* Update Kconfig to default to building as a module.
* Remove an erroneous printk.
* Simply comments for string flag (since we now leave the handling to the caller).

v9 (2007-12-07)

* Add back missing MODULE_DEVICE_TABLE for autoloading
* Checkpatch fixes

v10 (2007-12-12)

* Workaround broken GUIDs declared expensive without a WCxx method.
* Minor cleanups

v11 (2007-12-17)

* More fixing for broken GUIDs declared expensive without a WCxx method.
* Add basic EmbeddedControl region handling.

v12 (2007-12-18)

* Changed EC region handling code, as per Alexey's comments.

v13 (2007-12-27)

* Changed event handling so that we can have one event handler registered per GUID, as per Matthew Garrett's suggestion.

v14 (2008-01-12)

* Remove ACPI debug statements

v15 (2008-02-01)

* Replace two remaining 'x == NULL' type tests with '!x'

v16 (2008-02-05)

* Change MAINTAINERS entry, as I am not, and never have been, paid to work on WMI
* Remove 'default' line from Kconfig

---

 MAINTAINERS           |    7 
 drivers/acpi/Kconfig  |   10 +
 drivers/acpi/Makefile |    1 
 drivers/acpi/wmi.c    |  710 +++++++++++++++++++++++++++++++++++++++++++++++++
 include/linux/acpi.h  |   20 +
 5 files changed, 748 insertions(+), 0 deletions(-)
 create mode 100644 drivers/acpi/wmi.c

index 58b1603..2421b20 100644
@@ -259,6 +259,13 @@ L:	[email protected]
 W:	http://acpi.sourceforge.net/
 S:	Supported
 
+ACPI WMI DRIVER
+P:      Carlos Corbacho
+M:      [email protected]
+L:      [email protected]
+W:      http://www.lesswatts.org/projects/acpi/
+S:      Maintained
+
 ADM1025 HARDWARE MONITOR DRIVER
 P:	Jean Delvare
 M:	[email protected]

index 5583729..0065f37 100644
@@ -200,6 +200,16 @@ config ACPI_NUMA
 	depends on (X86 || IA64)
 	default y if IA64_GENERIC || IA64_SGI_SN2
 
+config ACPI_WMI
+	tristate "WMI (EXPERIMENTAL)"
+	depends on EXPERIMENTAL
+	help
+	  This driver adds support for the ACPI-WMI mapper device (PNP0C14)
+	  found on some systems.
+
+	  NOTE: You will need another driver or userspace application on top of
+	  this to actually use anything defined in the ACPI-WMI mapper.
+
 config ACPI_ASUS
         tristate "ASUS/Medion Laptop Extras"
 	depends on X86

index 456446f..f29812a 100644
@@ -55,6 +55,7 @@ obj-$(CONFIG_ACPI_THERMAL)	+= thermal.o
 obj-$(CONFIG_ACPI_SYSTEM)	+= system.o event.o
 obj-$(CONFIG_ACPI_DEBUG)	+= debug.o
 obj-$(CONFIG_ACPI_NUMA)		+= numa.o
+obj-$(CONFIG_ACPI_WMI)		+= wmi.o
 obj-$(CONFIG_ACPI_ASUS)		+= asus_acpi.o
 obj-$(CONFIG_ACPI_TOSHIBA)	+= toshiba_acpi.o
 obj-$(CONFIG_ACPI_HOTPLUG_MEMORY)	+= acpi_memhotplug.o

index de09704..9f2ee42 100644
@@ -191,6 +191,26 @@ extern int ec_transaction(u8 command,
 
 #endif /*CONFIG_ACPI_EC*/
 
+#if defined(CONFIG_ACPI_WMI) || defined(CONFIG_ACPI_WMI_MODULE)
+
+typedef void (*wmi_notify_handler) (u32 value, void *context);
+
+extern acpi_status wmi_evaluate_method(const char *guid, u8 instance,
+					u32 method_id,
+					const struct acpi_buffer *in,
+					struct acpi_buffer *out);
+extern acpi_status wmi_query_block(const char *guid, u8 instance,
+					struct acpi_buffer *out);
+extern acpi_status wmi_set_block(const char *guid, u8 instance,
+					const struct acpi_buffer *in);
+extern acpi_status wmi_install_notify_handler(const char *guid,
+					wmi_notify_handler handler, void *data);
+extern acpi_status wmi_remove_notify_handler(const char *guid);
+extern acpi_status wmi_get_event_data(u32 event, struct acpi_buffer *out);
+extern bool wmi_has_guid(const char *guid);
+
+#endif	/* CONFIG_ACPI_WMI */
+
 extern int acpi_blacklisted(void);
 #ifdef CONFIG_DMI
 extern void acpi_dmi_osi_linux(int enable, const struct dmi_system_id *d);

This is a driver for newer Acer (and Wistron) laptops. It adds wireless radio and bluetooth control, and on some laptops, exposes the mail LED and LCD backlight.

v1:

* Initial release

v2:

* Replace left over ACPI references with WMI
* Add GUID based autoloading (depends on future work to WMI)
* Add DMI based autoloading (backup solution until WMI sysfs/ class work is available)
* Checkpatch fixes

v3:

* Add new EC quirks for Aspire 3100 & 5100, and Extensa 5220

v4:

* Simplified internal handling of WMID and AMW0 devices
* Add autodetection for bluetooth and maximum brightness on AMW0 V2 and WMID laptops.

v5:

* Add EC quirk for Medion MD 98000
* Add autodetection for AMW0, and mail LED on AMW0 and AMW0 V2.
* Improve error handling
* Fix AMW0 V2 bluetooth and wireless, by using both WMID and AMW0 methods to ensure that the correct value is always set.

v6:

* Fix 'use before initialisation' bug with quirks.

v7

* Fix bug on AMW0 where acer-wmi would exit if a mail LED was not detected.
* Add Acer Aspire 9110 mail LED support
* Fix section mismatch warnings

---

 MAINTAINERS             |    7 
 drivers/misc/Kconfig    |   16 +
 drivers/misc/Makefile   |    1 
 drivers/misc/acer-wmi.c | 1109 +++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 1133 insertions(+), 0 deletions(-)
 create mode 100644 drivers/misc/acer-wmi.c

index 2421b20..12bda1b 100644
@@ -209,6 +209,13 @@ L:	[email protected]
 W:	http://www.adaptec.com/
 S:	Supported
 
+ACER WMI LAPTOP EXTRAS
+P:	Carlos Corbacho
+M:	[email protected]
+L:	[email protected] (subscribers-only)
+W:	http://code.google.com/p/aceracpi
+S:	Maintained
+
 ACPI
 P:	Len Brown
 M:	[email protected]

index f20c30c..9f20faa 100644
@@ -92,6 +92,22 @@ config TIFM_7XX1
           To compile this driver as a module, choose M here: the module will
 	  be called tifm_7xx1.
 
+config ACER_WMI
+        tristate "Acer WMI Laptop Extras (EXPERIMENTAL)"
+	depends on X86
+	depends on EXPERIMENTAL
+	depends on ACPI
+	depends on ACPI_WMI
+	depends on LEDS_CLASS
+	depends on BACKLIGHT_CLASS_DEVICE
+	---help---
+	  This is a driver for newer Acer (and Wistron) laptops. It adds
+	  wireless radio and bluetooth control, and on some laptops,
+	  exposes the mail LED and LCD backlight.
+
+	  If you have an ACPI-WMI compatible Acer/ Wistron laptop, say Y or M
+	  here.
+
 config ASUS_LAPTOP
         tristate "Asus Laptop Extras (EXPERIMENTAL)"
         depends on X86

index a9e8faf..7adf02f 100644
@@ -6,6 +6,7 @@ obj- := misc.o	# Dummy rule to force built-in.o to be made
 obj-$(CONFIG_IBM_ASM)		+= ibmasm/
 obj-$(CONFIG_HDPU_FEATURES)	+= hdpuftrs/
 obj-$(CONFIG_MSI_LAPTOP)     += msi-laptop.o
+obj-$(CONFIG_ACER_WMI)     += acer-wmi.o
 obj-$(CONFIG_ASUS_LAPTOP)     += asus-laptop.o
 obj-$(CONFIG_ATMEL_SSC)		+= atmel-ssc.o
 obj-$(CONFIG_LKDTM)		+= lkdtm.o

Create a 'wmi' class, and populate it with a virtual device for each GUID. This also allows us to autoload WMI drivers based on GUID
via MODULE_ALIAS.

Under each GUID are a set of files that can be read and written to from userspace (these will be fully documented in a later patch).

For now, the length of the GUID name/ directory is limited to 19 characters, due to the current hardcoded limit on bus_id. When this is fixed, this can be changed in the code.

v1 (2007-11-03)

* Initial release

v2 (2007-11-07)

* Split out into a separate patch

v3 (2007-11-20)

* Convert kobject storage to using kernel list structures.
* Change instance handling - store input data on a per instance basis, rather than a per GUID.
* Add locking to methods - method_id (write) and data (read & write) should all be mutually exclusive - we do not want the input data to change when we are trying to execute a method.
* Change method calling semantics: when input is written to 'data', store it, but don't execute the method until 'data' is read. This is due to the fact that it is perfectly acceptable to have a WMI method that does not take any input (and it is easier to trigger an execute on reading the file, and not return anything if there is nothing to return, rather than trying to write values that aren't required, or may cause ACPI evaluation to fail on the method).
* Do not try and convert String's from ASCII to Unicode - instead, only handle ASCII (as per ACPI), and leave it up to userspace to convert to/ from whatever encoding they wish to use.

v4 (2007-11-28)

* Add code to remove sysfs files on module removal

v5 (2007-12-08)

* Convert to a class device, instead of trying to manually create and manipulate kobject's - this allows us to add module autoloading for WMI based drivers, and will (hopefully) be less likely to break with the latest round of kobject changes.
* Convert GUIDs to use a 'flat' structure - add two new files:
instance and instance_count, and use these to provide the instance to call for a given GUID (while still communicating the maximum number of instances available - for now, we will always respect instance_count when setting instance - so any instance > instance_count will be discarded).

v6 (2007-12-12)

* Add string file - this reports back if the GUID has the string flag set.

v8 (2008-01-18)

* Add new in kernel function, wmi_get_device(), to take advantage of the class and virtual devices, and return the virtual device for a GUID.

v9 (2008-02-04)

* Fold in bus_id length workaround

---

 drivers/acpi/Kconfig |   10 +
 drivers/acpi/wmi.c   |  547 ++++++++++++++++++++++++++++++++++++++++++++++++++
 include/linux/acpi.h |    1 
 3 files changed, 556 insertions(+), 2 deletions(-)

index 0065f37..646b6f7 100644
@@ -210,6 +210,16 @@ config ACPI_WMI
 	  NOTE: You will need another driver or userspace application on top of
 	  this to actually use anything defined in the ACPI-WMI mapper.
 
+config ACPI_WMI_SYSFS_DEVEL
+	bool "WMI future sysfs interface"
+	default n
+	depends on ACPI_WMI
+	depends on SYSFS
+	help
+	  This creates a sysfs interface for the GUIDs associated with WMI.
+	  This is currently in development, so should only be enabled by testers
+	  or developers.
+
 config ACPI_ASUS
         tristate "ASUS/Medion Laptop Extras"
 	depends on X86

index 9f2ee42..8cbbeb2 100644
@@ -208,6 +208,7 @@ extern acpi_status wmi_install_notify_handler(const char *guid,
 extern acpi_status wmi_remove_notify_handler(const char *guid);
 extern acpi_status wmi_get_event_data(u32 event, struct acpi_buffer *out);
 extern bool wmi_has_guid(const char *guid);
+extern int wmi_get_device(const char *guid, struct device **dev);
 
 #endif	/* CONFIG_ACPI_WMI */
 

This is based on the 2004 out-of-tree work of Jamey Hicks, to add support via WMI for controlling the jog dial and wireless on these tablets.

v1:

Original release

v2:

As per Joshua Wise's comments, change bluetooth to jogdial (an error from the original driver).

---

 MAINTAINERS               |    5 +
 drivers/misc/Kconfig      |    9 +
 drivers/misc/Makefile     |    1 
 drivers/misc/tc1100-wmi.c |  290 +++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 305 insertions(+), 0 deletions(-)
 create mode 100644 drivers/misc/tc1100-wmi.c

index 12bda1b..2685c06 100644
@@ -1803,6 +1803,11 @@ P:	Jaroslav Kysela
 M:	[email protected]
 S:	Maintained
 
+HP COMPAQ TC1100 TABLET WMI EXTRAS DRIVER
+P:	Carlos Corbacho
+M:	[email protected]
+S:	Odd Fixes
+
 HPET:	High Precision Event Timers driver (hpet.c)
 P:	Clemens Ladisch
 M:	[email protected]

index 9f20faa..78cd338 100644
@@ -142,6 +142,15 @@ config FUJITSU_LAPTOP
 
 	  If you have a Fujitsu laptop, say Y or M here.
 
+config TC1100_WMI
+	tristate "HP Compaq TC1100 Tablet WMI Extras"
+	depends on X86 && !X86_64
+	depends on ACPI
+	depends on ACPI_WMI
+	---help---
+	  This is a driver for the WMI extensions (wireless and bluetooth power
+	  control) of the HP Compaq TC1100 tablet.
+
 config MSI_LAPTOP
         tristate "MSI Laptop Extras"
         depends on X86

index 7adf02f..1f41654 100644
@@ -9,6 +9,7 @@ obj-$(CONFIG_MSI_LAPTOP)     += msi-laptop.o
 obj-$(CONFIG_ACER_WMI)     += acer-wmi.o
 obj-$(CONFIG_ASUS_LAPTOP)     += asus-laptop.o
 obj-$(CONFIG_ATMEL_SSC)		+= atmel-ssc.o
+obj-$(CONFIG_TC1100_WMI)	+= tc1100-wmi.o
 obj-$(CONFIG_LKDTM)		+= lkdtm.o
 obj-$(CONFIG_TIFM_CORE)       	+= tifm_core.o
 obj-$(CONFIG_TIFM_7XX1)       	+= tifm_7xx1.o

ACPI: WMI: Add initial documentation

Add initial documentation for WMI-ACPI, giving basic information for WMI kernel and userspace driver writers.

===
ChangeLog

v1 (2007-11-28)

Initial version

v2 (2007-12-08)

Update with latest changes to sysfs interface

v3 (2008-02-05)

Update

---
Added SOB this time... (and a few trivial fixes)

This replaces: [PATCH 5/5] ACPI: WMI: Add documentation

(AKA - I shouldn't send a patch series out at 2am...)

 Documentation/acpi/wmi.txt |  131 ++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 131 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/acpi/wmi.txt

new file mode 100644
index 0000000..4d243aa
@@ -0,0 +1,131 @@
+ACPI-WMI mapping driver
+
+Copyright (C) 2007-2008 Carlos Corbacho <[email protected]>
+
+Updated: 5th February 2008
+
+1) About this guide
+
+This guide is a basic introduction on how to interact with the ACPI-WMI mapper
+driver in the kernel - it presumes you already have a basic knowledge of
+ACPI-WMI, ACPI and the hardware you are writing the driver for.
+
+2) What is ACPI-WMI
+
+At its simplest, ACPI-WMI is a proprietary extension to the ACPI specification
+from Microsoft to allow WMI (their implementation of WBEM) to access
+instrumentation data and methods in ACPI from userspace, via the ACPI _HID
+device PNP0C14.
+
+3) What is the ACPI-WMI mapper
+
+The Linux ACPI-WMI driver is the implementation of this mapper for Linux.
+
+NOTE: The mapper does not do anything itself with the ACPI-WMI devices - it
+simply makes their functionality available to other drivers and userspace.
+
+4) Implementation
+
+A general note:
+
+ACPI-WMI has no knowledge of the size of the data blocks passed to/ from
+ACPI-WMI - this is not encoded in the DSDT, and is usually only available in
+the form of a MOF file. If this is not available, you will need to analyze
+the DSDT to get this information.
+
+You will therefore need to know in advance the size of any data structures
+to handle them.
+
+Userspace:
+
+ACPI-WMI is exposed to userspace via sysfs and netlink. Data and methods are
+exposed through sysfs, events are sent via netlink.
+
+Accessing ACPI-WMI directly through sysfs is generally not recommended -
+ideally, this should be done by a userspace library, which could also deal
+with the netlink events.
+
+The sysfs interface is in /sys/devices/virtual/wmi for WMI methods and data, as
+follows:
+
+/sys/devices/virtual/wmi/
+|
+|-> <GUID>/
+ |-> type (method, data, event)
+
+Method & data blocks
+ |-> instance (instance to execute)
+ |-> instance_count (read only - maximum number of instances available)
+ |-> data (binary data file - write input data to file, read file
+           to execute method and/ or retrieve data).
+
+To read/ write a data block, instance must be set first.
+
+Method only
+ |-> method_id (write value of method id to execute)
+
+To execute a method, instance and method_id must be set first.
+
+Events - passed to userspace via netlink. However, the extra WMI data
+associated with an event is exposed through sysfs.
+
+ |-> notification (ACPI event value)
+ |-> data (binary data file - WMI data associated with the event)
+
+Kernel interface:
+
+For drivers that want to bypass userspace (either because WBEM is overkill,
+or a userspace application is not really appropriate for want you want to do),
+and talk directly to ACPI-WMI, then the mapper also exports functions
+to do this - these are essentially thin wrappers around ACPI, so if you are
+familiar with writing an ACPI driver, then writing a WMI driver is not much more
+of a stretch.
+
+The exported ACPI-WMI functions can be found in <linux/acpi.h>
+
+The most important differences between ACPI and WMI drivers are:
+
+A) WMI based drivers should be platform drivers, not ACPI drivers.
+
+B) ACPI details such as handles and/ or path names are hidden; you use GUIDs as
+   the unique identifier to call methods instead (you don't need to care either
+   about multiple PNP0C14 devices existing - the GUIDs are always unique, and
+   these are what you will work with).
+
+C) In your probe() function, you should use wmi_has_guid() to look for the
+   GUID(s) you need for your driver.
+
+For the in kernel interface, the following functions are available:
+
+wmi_evaluate_method():
+
+Evaluate a WMI method.
+
+wmi_query_block():
+
+Return the contents of a WMI data block.
+
+wmi_set_block()
+
+Set the contents of a WMI data block.
+
+wmi_install_notify_handler():
+wmi_remove_notify_handler():
+
+Install and/ or remove a handler for a WMI event - one handler per GUID.
+
+wmi_get_event_data():
+
+Return the data associated with a given WMI event.
+
+wmi_has_guid():
+
+Returns true if a given GUID is available on the system.
+
+wmi_get_device():
+
+Return a pointer to the virtual device associated with a GUID. If you need to
+set a parent device (e.g. for an input device), use this.
+
+
+[1] http://www.microsoft.com/whdc/system/pnppwr/wmi/wmi-acpi.mspx

I recommend skipping WMI on IA64 unless/until a real need to support it emerges. There are no WMI extensions on the Intel Tiger or Hitachi Fusion IA64 boxes I have access to.

thanks,
-Len

Ok. The only other vendors I really have in mind are HP and Fujitsu, since both those vendors use WMI on their laptops, so they would be my most likely candidates to have WMI on an IA64 box (if anyone actually does use WMI on IA64).

Len:

You can either add a 'depends on X86' to WMI when you apply patch #1 from the second WMI series; or I can send another patch out later on top of this series to do this, once you replace the old patches in acpi-test - whichever is easiest for you)

-Carlos

E-Mail: [email protected]
Web: strangeworlds.co.uk
GPG Key ID: 0x23EE722D

I'm starting to have some serious doubts about using sysfs for communicating with userspace (I'm happy with the class/ virtual device ID idea, and I don't see that being dropped, since it also solves the WMI autoloading problem quite neatly - but the extra sysfs files added on to allow userspace to interact with WMI are where I have a problem).

The problem is that a lot of the interactions with WMI are transactional - we pass something in, and we expect to get something out, and we don't want anything to happen in the middle to that data.

At the moment, this is the snippet of (Python) code I have to execute a WMI method from userspace (instance and method_id in this case are just integers, data_in and data_out can be any data structure, and are whatever the WMI method accepts & returns, respectively):

def evaluate_method(guid, instance, method_id, data_in, data_out):
# Check that the instance is not bigger than the allowed maximum # The maximum is defined by the GUID entry in the DSDT instance_count_file = open(path + guid + "/instance_count", "r")

if int(instance) > int(instance_count_file.read()):
print "Instance is outside allowed maximum range" exit()

instance_count_file.close()

# Specify the instance we want to execute instance_file = open(path + guid + "/instance", "w") instance_file.write(instance)

# Specify the method we want to execute method_id_file = open(path + guid + "/method_id", "w") method_id_file.write(method_id)

# Write the input data in
data_file = open(path + guid + "/data", "wb") data_file.write(data_in) data_file.close()

# Read the data back to trigger execution data_file = open(path + guid + "/data", "rb") data_out = data_file.read() data_file.close()

method_id_file.close()
instance_file.close()

Unfortunately, as you can see this isn't nice, and very racy. To point out the more glaring flaws:

1) instance and method_id can be changed before we start reading and writing in any data.

2) Executing a method involves reading back from the 'data' file (but if we don't care about the output, this makes little sense). If anything changes before this, then either the method will fail, or we may not execute what we intended to.

3) For method execution, this really comes across as rather 'clunky' means to do so

At this point, I'm seriously looking into replacing the sysfs userspace interface with ioctl's instead, but I'd like some thoughts either way, as I'm not that sure where to go from here.

-Carlos

E-Mail: [email protected]
Web: strangeworlds.co.uk
GPG Key ID: 0x23EE722D

How could I tell whether our HP systems use WMI?

Bjorn

Do you have any PNP0C14 or *pnp0c14 _HID objects defined in the DSDTs for your systems? If not, then your systems don't use WMI.

-Carlos

E-Mail: [email protected]
Web: strangeworlds.co.uk
GPG Key ID: 0x23EE722D

I looked at DSDTs for a few HP ia64 systems (rx7620, rx8640, and superdome), and none has a PNP0C14 object.

Will do.

I was always taught that the correct way was to leave a space.

However, I will fix this.

There is currently no userspace application that can handle this (netlink is also only used for event passing, as stated).

-Carlos

E-Mail: [email protected]
Web: strangeworlds.co.uk
GPG Key ID: 0x23EE722D

On these two points, we could use locking (but this would only be advisory, and rely on other programs not trying to write while we do), but we'd need to rejig how this works a bit (since reading 'data' here triggers execution.

(So, basically, in future, shoving this all into a C library to abstract the WMI sysfs file access).

This point is still valid.

Maybe changing a method to the following:

<GUID>/

|--> instance_count
|--> instance
|--> method_id
|--> in
|--> out
|--> execute

Then to execute a method:

1) Write lock instance, method_id, in, out and execute.

2) Write the instance and method_id to be executed to their respective files. Write the input data for the method to 'in'.

3) Write '1' to execute the method, store the returned data in 'out' (writing '0' to 'execute' would clear everything instead). (We can always return the error code by reading execute).

4) Read 'out' to retrieve any data.

(I don't want to make reading 'out' trigger the execution, since we can't guarantee a read lock between languages).

For data blocks, we can do something similar.

Any thoughts? It's still a little clunky, and I'm still not sure whether an ioctl would still be preferable to all this?

-Carlos

E-Mail: [email protected]
Web: strangeworlds.co.uk
GPG Key ID: 0x23EE722D

In either case, ioctl or sysfs, a library is probably appropriate. However, with the ioctl, it sounds like the driver is able to enforce consistency of a transaction, while multiple users of a sysfs I/F may get confused, or worse.

So the question is if the sysfs I/F is useful for development or not, since it doesn't look like the right I/F in the long run.

Shall I drop patches #4 and #5, or would you like to send an update?

thanks,
-Len

Hi Carlos,

Now that we're getting a proliferation of WMI drivers (I'm working on a Dell one at the moment), it'd be nice to be able to get the module autoloading support in. BUS_ID still seems to be limited to 20 bytes, though. Any thoughts on the best way to go from here?

Matthew Garrett | [email protected]

Can we abuse uevent and cram all the GUID's into just one MODALIAS line?

Alternatively, maybe just have the directories numbered 1 to X, and have a uevent file under each, since we don't care about trying to abuse sysfs to let userspace talk to WMI anymore.

-Carlos

E-Mail: [email protected]
Web: strangeworlds.co.uk
GPG Key ID: 0x23EE722D

Looking at the udev rules, I suspect we need one event per GUID.

Yeah, that'd work for me.

Matthew Garrett | [email protected]

Subject was:
Re: [PATCH 4/5] ACPI: WMI: Add sysfs userspace interface

You should add Kay if you get stuck...
Based on Kay's recent description on the linux-acpi list I set up this documentation. IMO it's worth adding, Andi, Kay?

Thomas

-----
From: Kay Sievers <[email protected]>
Documentation: Add udev.txt based on Kay's short summary

index 5b5aba4..ce9dd7a 100644
@@ -361,6 +361,8 @@ time_interpolators.txt
 	- info on time interpolators.
 tty.txt
 	- guide to the locking policies of the tty layer.
+udev.txt
+	- How autoloading of modules work.
 uml/
 	- directory with information about User Mode Linux.
 unicode.txt

new file mode 100644
index 0000000..ceb0e40
@@ -0,0 +1,37 @@
+Maintainer of udev: Kay Sievers <[email protected]>
+
+Abstract:
+This is about getting a specific driver automatically loaded
+at boot time via udev. Depending on whether the kernel detects
+that the HW, the driver is supporting, is available.
+
+
+Devices, any kind of device, can export a match, based on specific
+properties of the subsystem it belongs to. In most cases its the same
+property/id that is used inside the kernel, to find a (already loaded)
+driver which will bind this device. 
+
+Any unique string, hardware ID's, whatever, are stuffed into a modalias,
+prefixed by "<subsystem>:" to be unique.
+
+PCI and USB are pretty obvious, they just stuff all their hardware ID'S
+into a string, in a defined order, and let every device export that value
+to userspace by MODALIAS environment key and the "modalias" sysfs file.
+Other subsystem may have simple strings to match, they define
+themselves.
+
+Now, the drivers contain "match id tables" which are used by the core
+to bind devices to drivers. These tables area made available to
+file2alias.c in the module postprocessing, and will end up in the
+module file itself. The string is mangled to contain wildcards, so
+they can just be fnmatch()'d against the modalias value, which the
+devices export.
+
+The string embedded in the modules are extracted by depmod, and put
+into the modules.aliases file in /lib/modules/. Every time modprobe
+is called with an alias, it searches through this file and loads all
+modules which contained a matching alias string.
+
+Udev does nothing but stupidly running modprobe for every device which
+contains MODALIAS in the event environment, and passes $MODALIAS as
+an argument to modprobe.

How many id's of what size do we have? What would be the maximum string length?

A "uevent" file? That file is mechanic of the driver-core and created automatically for every device. It has well defined behaviour, like you can trigger a uevent action, or read the event environment. Custom subdirs with custom "uevent" files would not do anything, I guess. You would need a "struct device" for every directory and uevent file.

What do you have in mind? Care to paste-in some example strings?

Oh, that sounds a bit too much like "talking". I guess, it should be rewritten, before it goes into the Documentation directory. :)

Thanks,
Kay

...

It's better than nothing.
I won't rewrite it. I lost too much time already the last days with descriptions.

I mean, if you read it, you know how it works?
No need to provide a formal perfect paper?

Thomas

Now that we've got the new device_name() stuff, is it possible to add support for generating the modalias uevents in wmi? It'd be good to get the autoloading sorted properly.

Matthew Garrett | [email protected]

Mario asked me about this yesterday.

I have a patch I've started working on - it compiles and at least boots on my laptop, but not thorough tested or finished yet:

http://files.strangeworlds.co.uk/PATCH-4_5-RFC-ACPI-WMI-Add-sysfs-userspace-
interface.mbox

I can try and pick it up again if I have time, though I'm happy if anyone else wants to pick this up.

-Carlos

E-Mail: [email protected]
Web: strangeworlds.co.uk
GPG Key ID: 0x23EE722D