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 diff --git a/Documentation/acpi/wmi.txt b/Documentation/acpi/wmi.txt new file mode 100644 index 0000000..4d243aa --- /dev/null +++ b/Documentation/acpi/wmi.txt @@ -0,0 +1,131 @@ +ACPI-WMI mapping driver + +Copyright (C) 2007-2008 Carlos Corbacho <carlos@xxxxxxxxxxxxxxxxxxx> + +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 - To unsubscribe from this list: send the line "unsubscribe linux-acpi" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
