SoC平台的Windows ACPI 设计指导 详解

Windows的ACPI对于Windows驱动开发的人员来说一直是比较难以理解的东西，现将Windows的ACPI的资料详细说明，希望对广大网友有所帮助。

Windows ACPI Design Guide for SoC Platforms

September 10, 2013

Abstract

This paper provides information about Advanced Configuration and Power Interface (ACPI) support in Windows for SoC platforms. Firmware and system designers can use the guidelines in this paper to ensure that the Windows operating system runs properly on their platforms. See the documentation for all firmware requirements.

This information applies to the following operating systems:
        Windows 8.1

        Windows 8

       

References and resources discussed here are listed at the end of this paper.

The current version of this paper is maintained on the Web at:
       

Disclaimer: This document is provided "as-is". Information and views expressed in this document, including URL and other Internet website references, may change without notice. Some information relates to pre-released product which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here. You bear the risk of using it.

Some examples depicted herein are provided for illustration only and are fictitious. No real association or connection is intended or should be inferred.

This document does not provide you with any legal rights to any intellectual property in any Microsoft product. You may copy and use this document for your internal, reference purposes. You may modify this document for your internal, reference purposes.

© 2013 Microsoft. All rights reserved.

Contents

 TOC \o "1-3" \h \z \u

1       Purpose

This paper describes Advanced Configuration and Power Interface (ACPI) support in Windows for hardware platforms that use System on a Chip (SoC) integrated circuits. This support is based on the ACPI 5.0 specification, found at . ACPI 5 has many enhancements to enable support of non-PC architectures, which include SoC-based mobile platforms, but carries forward many useful features already supported by Windows. The purpose of this paper is to direct implementers to the parts of ACPI 5 that specifically apply to SoC platforms, and to describe best practices for implementing the SoC-specific features in ACPI to run Windows on these platforms.

1.1  Scope

The target audience for this paper is firmware and system designers who require guidance for firmware support and implementation. Observation and adherence to these guidelines will help ensure proper functionality of Windows on SoC platforms.

This design guidance specifically targets hardware-reduced ACPI platforms that support low-power S0 idle. However, most of the guidance also applies to any platform compliant with ACPI 5 and running Windows 8 or greater. In addition, this paper assumes either a clamshell form factor or a wireless, multi-touch-only mobile platform. It therefore limits itself to technologies expected to be widely used on such platforms. For technologies not covered in this paper, the reader is referred to the ACPI specification itself for implementation information.

1.2  Firmware Revision Support

Windows supports firmware revisions based on the Advanced Configuration and Power Interface (ACPI)  specification, revision 5.0 or later.

Note  Windows supports a subset of functionality defined in the ACPI 5.0 specification. Windows does not have an explicit check against higher revisions of the firmware. The operating system will support firmware that conforms to higher revisions of the ACPI specification if this firmware contains the necessary support, as described in this paper.

2       ACPI Support in Windows

The subset of ACPI 5 features required to support Windows on SoC platforms is summarized in the following table, and is covered in more detail in later sections of this paper.

Feature	Section of ACPI 5.0 specification	Notes
System description tables
	5.2.5	Root System Description Pointer (RSDP)
	5.2.7, 5.2.8	Either of Root (RSDT) or Extended (XSDT) System Description Tables
	5.2.9	Fixed ACPI Description Table (FADT)
	5.2.12	Multiple APIC Description Table (MADT)
	5.2.24	Generic Timer Description Table (GTDT)
	5.2.6 (specification is here)	Core System Resources Table (CSRT)
	5.2.6 (specification is )	Debug Port Table 2 (DBG2)
	5.2.11.1	Differentiated System Description Table (DSDT)
	5.2.11.2	Secondary System Description Table (SSDT)
Device management
	6.1	Device Identification Objects
	6.2	Device Configuration Objects
GPIO
	5.6.5.1	GPIO controller devices
	5.6.5	GPIO-signaled ACPI events
	6.4.3.8.1, 19.5.53, .54	GPIO resource descriptors and macros
	5.5.2.4.4	GeneralPurposeIO Operation Regions
Simple peripheral bus (SPB)
	6.4.3.8.2, 19.5.55, .118, .134	SPB resource descriptors and macros
		GenericSerialBus Operation Regions
Device power management	3.3
	7.1	Power Resources
	7.2	Device Power Management Objects
ACPI-defined devices	9.0, 10
	9.5	Control Method Power Button
	9.4	Control Method Lid Device
	10.2	Control Method Battery device
	9.18	Control Method Time and Alarm device
	11	Thermal Zones
Device-specific support
	8.4	Processors
	Appendix B	Displays
	6.1.8,  9.13	USB
		SD bus
		Cameras
		HID-over-I2C devices
	3.2.1, 4.8.2.2.1.2, .3	Buttons
		Dock and convertible PC sensors

2.1  ACPI Hardware Features

2.1.1  ACPI Hardware Specification

To support SoCs, Windows does not require hardware platforms to implement any of the features described in chapter 4, "ACPI Hardware Specification", of the ACPI 5.0 specification. ACPI fixed hardware features such as the following are not required:

·         Power Management (PM) timer

·         Real Time Clock (RTC) wake alarm

·         System Control Interrupt (SCI)

·         Fixed Hardware register set (PMx_* event/control/status registers)

·         GPE block registers (GPEx_* event/control/status registers)

·         Embedded controller

Platforms that do not implement the ACPI Fixed Hardware interface are referred to as hardware-reduced ACPI platforms. To indicate that a platform is hardware-reduced, set the HW_REDUCED_ACPI flag in the Fixed ACPI Description Table (FADT).

On hardware-reduced ACPI platforms, fixed hardware features such as power button, lid status, and so on, which have traditionally been implemented in ACPI-defined hardware, are replaced exclusively by their ACPI-defined software equivalents. For example, a Control Method Power Button is used instead of the Fixed Hardware equivalent.

Platforms that support the InstantGo feature (and the Connected Standby power mode) are exposed to Windows as platforms that provide the low-power S0-idle capability defined in ACPI 5.0. Therefore, the "Low Power S0 Idle Capable" flag in the FADT must be set.

Windows supports platforms that have low-power S0-idle capability regardless of whether they implement hardware-reduced ACPI or full ACPI. However, as required by the ACPI 5.0 specification, Windows does not use traditional sleep/resume features on platforms that have low-power S0-idle capability, regardless of ACPI configuration.

2.1.2  ACPI Events

As part of chapter 4, "ACPI Hardware Specification", of the ACPI 5.0 specification, a full-featured mechanism is defined for signaling hardware events. Windows supports many events defined in the specification, and this support carries over to SoC platforms. However, for hardware-reduced ACPI platforms, GPIO interrupts are used to signal the events, instead of the ACPI-defined GPE/SCI hardware. After an event is signaled, however, event handling is identical between hardware-reduced and full ACPI platforms. In both cases, the ACPI-specified event-handling mechanism invokes the appropriate control method (handler) for the event, which ultimately sends an ACPI-defined notification to the appropriate device driver.

For more information about GPIO-signaled ACPI events, see section 5.6.5, "GPIO-Signaled ACPI Events", of the ACPI 5.0 specification. For more information about the ACPI software event handling, see section 5.6.4, "General Purpose Event Handling", of the ACPI 5.0 specification.

2.2  System Description Tables

Implementation of the ACPI Hardware Specification is not required on SoC platforms, but much of the ACPI Software Specification is (or can be) required. ACPI defines a generic, extensible table-passing mechanism, plus specific tables for describing the platform to the operating system. Table structures and headers, including ID and checksum fields, are defined in the ACPI 5.0 specification. Windows utilizes this table mechanism, as well as the specific tables described in the following paragraphs.

Note   The idea behind these tables is to enable generic software to support standard intellectual property (IP) blocks that can be integrated into various platforms in diverse ways. With the table strategy, the platform-variable attributes of a particular platform are provided in a table, and used by generic software to adapt itself to the specific set of IP blocks integrated into the platform. This software can therefore be written once, well-tested, and optimized over time.

2.2.1  Root System Description Pointer (RSDP)

Windows depends on UEFI firmware to boot up the hardware platform. Hence, Windows will use the EFI system table to locate the RSDP, as described in section 5.2.5.2, "Finding the RSDP on UEFI Enabled Systems", of the ACPI 5.0 specification. The platform firmware fills in the address of either the RSDT or XSDT in the RSDP. (If both table addresses are provided, Windows will prefer the XSDT. )

2.2.2  Root System Description Table (RSDT)

The RSDT (or XSDT) includes pointers to any other system description tables provided on the platform. Specifically, this table contains pointers to the following:

?        The Fixed ACPI Hardware Table (FADT)

?        The multiple interrupt controller table (MADT)

?        Optionally, the Core System Resource Table (CSRT)

?        The Debug Port Table 2 (DBG2)

?        The Boot Graphics Resource Table (BGRT)

?        The Firmware Performance Data Table (FPDT)

?        The base system description table (DSDT)

?        Optionally, additional system description tables (SSDT)

All these tables are described in the following sections.

2.2.3  Fixed ACPI Description Table (FADT)

The Fixed ACPI Hardware Table (FADT) contains important information about the various Fixed Hardware features available on the platform. To support hardware-reduced ACPI platforms, ACPI 5 extends the FADT table definition as follows:

?        The Flags field within the FADT (offset 112) has two new flags:

o   HARDWARE_REDUCED_ACPI – Bit offset 20. Indicates that ACPI hardware is not available on this platform. This flag must be set if the ACPI Fixed Hardware Programming Model is not implemented.

o   LOW_POWER_S0_IDLE_CAPABLE – Bit offset 21. Indicates that the platform supports low-power idle states within the ACPI S0 system power state that are more energy efficient than any Sx sleep state. If this flag is set, Windows will not try to sleep and resume, but will instead use platform idle states and Connected Standby.

?        The FADT Preferred_PM_Profile field (byte offset 45) has a new role entry, "Tablet". This role influences power management policy for the display and input, and affects the display of on-screen keyboards.

?        The "IA-PC Boot Architecture Flags" field (offset 109) has a new "CMOS RTC Not Present" flag (bit offset 5) to indicate that the PC's CMOS RTC is either not implemented, or does not exist at the legacy addresses. If this flag is set, the platform must implement the ACPI Time and Alarm Control Method device. For more information about this device, see section 2.7.3 later in this paper.

?        New fields are added to support traditional PC sleep/resume on hardware-reduced ACPI platforms. These fields are ignored by Windows, but must be present in the table for compliance.

?        If the HARDWARE_REDUCED_ACPI flag is set, all fields relating to the ACPI Hardware Specification are ignored by the operating system.

All other FADT settings retain their meanings from the previous version, ACPI 4. For more information, see section 5.2.9, "Fixed ACPI Description Table (FADT)", of the ACPI 5.0 specification.

2.2.4  Multiple APIC Description Table (MADT)

In PC implementations of ACPI, the Multiple APIC Description Table (MADT) and PC-specific interrupt controller descriptors are used to describe the system interrupt model. For ARM-based SoC platforms, ACPI 5 adds descriptors for the ARM Holdings' Generic Interrupt Controller (GIC) and GIC Distributor. Windows includes inbox support for the GIC and GIC Distributor. For more information about these descriptors, see sections 5.2.12.14, "GIC Structure", and 5.2.12.15, "GIC Distributor Structure", of the ACPI 5.0 specification.

The interrupt controller descriptor structures are listed immediately after the Flags field in the MADT. For ARM platforms, one descriptor is listed for each GIC, followed by one for each GIC Distributor. The GIC corresponding to the boot processor must be the first entry in the list of interrupt controller descriptors.

2.2.5  Generic Timer Description Table (GTDT)

As with the interrupt controller, there is a standard timer description table in ACPI. For ARM systems that utilize the GIT timer, ACPI's GTDT can be used to leverage the built-in support for the GIT in Windows.

2.2.6  Core System Resources Table (CSRT)

Core System Resources (CSRs) are shared hardware functions such as interrupt controllers, timers and DMA controllers that the operating system must serialize access to. Where industry standards exist for features such as timers and interrupt controllers (on both x86 and ARM architectures), Windows builds in support for these features based on the standard tables described in ACPI (for example, MADT and GTDT, discussed above). However, until the industry converges on DMA controller interface standards, there is a need to support some non-standard devices in the operating system.

Windows supports the concept of HAL extensions to address this issue. HAL extensions are SoC-specific modules, implemented as DLLs, that adapt the Windows HAL to a specific hardware interface of a specific class of CSR required by Windows. In order to identify and load these non-standard CSR modules, Microsoft has defined a new ACPI table. This table, which has a reserved signature of "CSRT" in the ACPI specification, must be included in the RSDT if non-standard CSRs are used on the platform.

The CSRT describes resource groups of CSRs, where each resource group identifies hardware of a particular type. Windows uses the identifier provided for the resource group to find and load the required HAL extension for this group. Resource groups within the CSRT might also contain individual resource descriptors, depending on the CSR type and the needs of the HAL extension. The format and use of these resource descriptors is defined by the HAL extension writer, who can make the extension much more portable and thereby support a variety of different SoC platforms simply by changing the resource descriptors contained in the CSRT.

To support maintenance of HAL extensions, and to manage the system resources used by these extensions, each resource group described in the CSRT must also be represented as a device within the platform's ACPI namespace (see section 2.2.8, "Differentiated System Description Table (DSDT)", below). The device identifiers used in the resource group header must match the identifiers used in the device's namespace node (see section 2.3.2, "Device Identification in ACPI", below). The existence of these resource group namespace devices allows the HAL extension to be serviced by the Windows Update Service.

For more information, see the Core System Resources Table (CSRT) specification at http://acpica.org/related-documents.

2.2.7  Debug Port Table 2 (DBG2)

Microsoft requires a debug port on all systems. To describe the debug port(s) built into a platform, Microsoft defines the Debug Port Table 2 (DBG2) for ACPI. This table specifies one or more independent port(s) for debugging purposes. The presence of the DBG2 table indicates that the platform includes at least one debug port. This table includes information about the identity and configuration of the debug port(s). The table is located in system memory with other ACPI tables, and must be referenced in the ACPI RSDT table.

Windows uses the Port Type value in the DBG2 table to identify and load the Kernel Debugger (KD) transport (for example, USB or serial) that the system requires. The KD transport then uses the Port Subtype value in the DBG2 table to identify the hardware interface used by the port. Other information in the DBG2 table specifies the system address of the port registers, which is used by the hardware interface module for the specified subtype. Finally, the DBG2 table must include a reference to the device node in the ACPI namespace that corresponds to the debug port. This reference enables Windows to manage conflicts between debugging use and normal use of the device, if any, and also to integrate the debugger with power transitions.

For more information, see the "Microsoft Debug Port Table 2 (DBG2)" specification at .

2.2.8  Differentiated System Description Table (DSDT)

In ACPI, peripheral devices and system hardware features on the platform are described in the Differentiated System Description Table (DSDT), which is loaded at boot, or in Secondary System Description Tables (SSDTs), which are loaded at boot or loaded dynamically at run time. For SoCs, the platform configuration is typically static, so the DSDT might be sufficient, although SSDTs can also be used to improve the modularity of the platform description.

ACPI defines an interpreted language (ACPI source language, or ASL) and an execution environment (ACPI virtual machine) for describing system devices and features, and their platform-specific controls, in an OS-agnostic way. ASL is used to define named objects in the ACPI namespace, and the ASL compiler (Asl.exe in Windows Driver Kit 8.1) is used to produce ACPI machine language (AML) byte code for transmission to the operating system in the DSDT. The Acpi.sys driver in Windows implements the ACPI virtual machine and interprets the AML byte code. An AML object might simply return description information. Or, an AML object might be a method that performs computation or does I/O operations. A control method is an executable AML object that uses the operating system's device drivers to do I/O operations on the platform hardware. ASL uses OpRegions to abstract the various address spaces accessible in the operating system. Control methods perform I/O operations as a series of transfers to and from named fields declared in OpRegions.

For more information about OpRegions, see section 5.5.2.4, "Access to Operation Regions", in the ACPI 5.0 specification. For more about ASL and control methods, see section 5.5, "ACPI Namespace", in the ACPI 5.0 specification.

Windows provides support for developing and debugging ASL code. The ASL compiler  includes a disassembler to enable the implementer to load a namespace from a debugging target. The ASL compiler can then be used to reapply the namespace to the target for rapid prototyping and testing—without having to flash the system firmware. In addition, the Windows Kernel Debugger, in conjunction with a checked (CHK) version of the Windows-provided Acpi.sys driver, supports tracing and analyzing AML execution. For more information, see the "ACPI Debugging" topic at .

2.2.8.1  ACPI Namespace

The namespace hierarchy must accurately model the platform's hardware topology, starting with the processor's system bus ("\_SB"). In general, a device that connects to a bus or controller appears as a child of that bus or controller device in the namespace. The following rules apply specifically to SoC platforms:

?        Memory-mapped functional blocks (including processors) appear directly under the \_SB node.

?        Peripheral devices that connect to some combination of simple peripheral bus (SPB) controllers and/or GPIO controllers describe their connections to these controllers as connection resources. For more information, see sections 2.4 and 2.5, which discuss GPIO and simple peripheral buses, later in this paper.

Peripherals that are connected in this way might appear directly under the \_SB node, or under a parent SPB or GPIO controller. The latter is preferred, when possible, because it indicates the device relationship directly in the namespace itself, instead of requiring the decoding of resources to discover the relationship.

?        Any functional blocks or peripherals connected through a standard bus that supports hardware enumeration (for example, SDIO and USB) do not need to appear in the namespace at all. However, you must include such devices under their parent controller in the namespace in certain cases. This is necessary with embedded USB HSIC or SDIO devices, for example, where platform-specific (non-standard) controls (for example, power switches, GPIO or SPB connections, and so on) are associated with the device as part of the system design. In this case, the standard parent bus driver enumerates the device, but the ACPI driver is loaded as a filter in the device stack to invoke the control methods for the non-standard controls on behalf of the bus driver, as needed.

?        Any "private" buses or devices (for example, I2S) that are dedicated to the use of one function driver (for example, the audio driver) do not need to appear in the namespace at all. However, in this case, any system resources used by the device must appear in the function device's resource list in the namespace. For more information, see section 2.3.3, "Device Configuration Objects", later in this paper.

ACPI defines many standard namespace objects and methods, but implementers can define new ones as needed. The ACPI-defined objects and methods are used for common operating system functions such as platform description (for example, device identification and system resource allocations), generic device control (for example, configuring resources and controlling power resources), or class-specific feature control (for example, dimming displays or reporting battery status). The sections that follow list the set of namespace objects used on SoC platforms, and include implementation guidance for using these objects with Windows.

2.3  Device Management Namespace Objects

2.3.1  Device Identification in Windows

Windows Plug and Play finds and loads device drivers based on a device identifier provided by the enumerator of the device. Enumerators are bus drivers that know how to extract identification information from the device. Some buses (such as PCI, SD, and USB) have hardware-defined mechanisms to do this extraction. For buses that do not (such as the processor bus or a simple peripheral bus), ACPI defines identification objects in the namespace.

The ACPI driver assembles the values found in these objects into a variety of device identifier strings that can identify a device very specifically, or quite generically, depending on the needs of the driver. Some of the string patterns created to identify ACPI-enumerated devices are:

ACPI\VEN_vvv[v]&DEV_dddd&SUBSYS_sss[s]nnnn&REV_rrrr

ACPI\VEN_vvv[v]&DEV_dddd&SUBSYS_sss[s]nnnn

ACPI\VEN_vvv[v]&DEV_dddd&REV_rrrr

ACPI\VEN_vvv[v]&DEV_dddd

ACPI\vvv[v]dddd

You can see the device identifiers that Windows creates for your device by opening Device Manager and inspecting the Hardware IDs and Compatible IDs properties of the enumerated device. Each of these strings is available to be specified in an INF file to identify the driver to load for the device. The order of INF matching is from the most specific hardware identifier (most preferred driver) to the least specific identifier (least preferred driver), so that drivers that know more about the specific features of the device can replace those that are less specific (and therefore support only a subset of the device features).

Device identifiers should be used only for INF matching, and should never be parsed or processed by the device driver. If the device driver has a need to identify the specific hardware it was loaded for, the recommended method is to have the INF file set appropriate registry keys at install time. The driver can then access these keys during initialization to obtain the required information.

2.3.2  Device Identification in ACPI

2.3.2.1  Hardware ID (_HID)

The minimum requirement for identifying a device in ACPI is the Hardware ID (_HID) object. _HID returns a string with the format of "ABC[D]xxxx", where "ABC[D]" is a 3- or 4-character string that identifies the manufacturer of the device (the "Vendor ID"), and xxxx is a hexadecimal number that identifies the specific device manufactured by that vendor (the "Device ID"). Vendor IDs must be unique across the industry. Microsoft allocates these strings to ensure that they are unique. Vendor IDs can be obtained from the Microsoft PNPID website at .

Note  ACPI 5 also supports the use of PCI-assigned vendor IDs in _HID and other identification objects, so you might not need to get a vendor ID from Microsoft. For more information about hardware identification requirements, see section 6.1.5, "_HID (Hardware ID)", of the ACPI 5.0 specification.

2.3.2.2  Compatible ID (_CID)

Microsoft has reserved the vendor ID "PNP" for devices that are compatible with inbox drivers shipped with Windows. Windows defines a number of device IDs for use with this vendor ID that can be used to load the Windows-provided driver for a device. A separate object, the Compatible ID (_CID) object, is used to return these identifiers. Windows always prefers Hardware IDs (returned by _HID) over Compatible IDs (returned by _CID) in INF matching and driver selection. This preference allows the Windows-provided driver to be treated as a default driver if a vendor-provided device-specific driver is not available. The Compatible IDs in the following table are newly created for use with SoC platforms.

Compatible ID	Description
PNP0C40	Windows-compatible button array
PNP0C50	HID-over-I2C compliant device
PNP0C60	Convertible laptop display sensor device
PNP0C70	Dock sensor device
PNP0D10	XHCI-compliant USB controller with standard debug
PNP0D15	XHCI-compliant USB controller without standard debug
PNP0D20	EHCI-compliant USB controller without standard debug
PNP0D25	EHCI-compliant USB controller with standard debug
PNP0D40	SDA standard-compliant SD host controller
PNP0D80	Windows-compatible system power management controller

                                               

2.3.2.3  Subsystem ID (_SUB), Hardware Revision (_HRV) and Class (_CLS)

ACPI 5 defines the _SUB, _HRV, and _CLS objects that can be used along with the _HID to create identifiers that more uniquely identify a specific version, integration, or hardware revision of a device, or to indicate membership in a PCI-defined device class. These objects are generally optional, but might be required by certain device classes in Windows. For more information about these objects, see section 6.1, "Device Identification Objects", of the ACPI 5.0 specification.

For serviceability, there is a WHCK requirement that device IDs on OEM systems be "four-part" IDs. The four parts are the vendor ID, the device ID, the subsystem vendor (OEM) ID, and the subsystem (OEM) device ID. Therefore, the Subsystem ID (_SUB) object is required for OEM platforms.

2.3.2.4  Device-Specific Method (_DSM)

The _DSM method is defined in section 9.14.1, "_DSM (Device Specific Method)", of the ACPI 5.0 specification. This method provides for individual, device-specific data and control functions that can be called by a device driver without conflicting with other such device-specific methods. The _DSM for a particular device or device class defines a UUID (GUID) that is guaranteed not to clash with other UUIDs. For each UUID, there is a set of defined functions that the _DSM method can implement to provide data or to perform control functions for the driver. Class-specific data and data formats are provided in separate device-class-specific specifications, and are also discussed later in this paper (see the device-class-specific sections).

2.3.2.5  Address (_ADR) and Unique ID (_UID)

Here are three additional requirements for device identification:

?        For devices that connect to a hardware-enumerable parent bus (for example, SDIO, USB HSIC), but that have platform-specific features or controls (for example, sideband power or wake interrupt), the _HID is not used. Instead, the device identifier is created by the parent bus driver (as discussed previously). In this case, though, the Address Object (_ADR) is required to be in the ACPI namespace for the device. This object enables the operating system to associate the bus-enumerated device with its ACPI-described features or controls.

?        On platforms where multiple instances of a particular IP block are used, so that each block has the same device identification objects, the Unique Identifier (_UID) object is necessary to enable the operating system to distinguish between blocks.

?        No two devices in a particular namespace scope can have the same name.

2.3.3  Device Configuration Objects

For each device identified in the namespace, the system resources (memory addresses, interrupts, and so on) consumed by the device must also be reported by the Current Resource Settings (_CRS) object. Note that reporting of multiple possible resource configurations (_PRS) and controls for changing a device's resource configuration (_SRS) are supported but optional.

New for SoC platforms are GPIO and simple peripheral bus (SPB) resources that a device can consume. See the following sections for more information. Also new for SoC platforms is a general-purpose fixed DMA descriptor. The FixedDMA descriptor supports the sharing of DMA controller hardware by a number of system devices. The DMA resources (request line and channel registers) statically allocated to a particular system device are listed in the FixedDMA descriptor. For more information, see section 19.5.49, "FixedDMA (DMA Resource Descriptor Macro)", of the ACPI 5.0 specification.

2.3.4  Device Status Changes

ACPI-enumerated devices can be disabled or removed for a variety of reasons. The Status (_STA) object is provided to enable such status changes to be communicated to the operating system. For a description of _STA, see section 6.3.7 of the ACPI 5.0 specification. Windows uses _STA  to determine if the device should be enumerated, shown as disabled, or not visible to the user. This control in the firmware is useful for many applications, including docking and USB OTG host-to-function switching.

Additionally, ACPI provides a notification mechanism that ASL can use to notify drivers of events in the platform, such as a device being removed as part of a dock. In general, when an ACPI device's status changes, the firmware must perform a "device check" or "bus check" notification to cause Windows to re-enumerate the device and re-evaluate its _STA. For information about ACPI notifications, see section 5.6.6, "Device Object Notifications", of the ACPI 5.0 specification,

2.3.5  Enable/Disable

As part of Windows Plug and Play, drivers are required to be capable of being dynamically enabled and disabled by the user or by the system (for example, for updating a driver).

On-SoC devices are integrated into the SoC chip and cannot be removed. Drivers for most on-SoC devices can be exempted from the requirements for enable and disable. For more information, see the document titled "Reducing PNP Requirements for SoC Drivers" on the Microsoft Connect website at . For those drivers that are not exempt, there are driver interfaces for indicating that the driver supports orderly removal. For more information about these interfaces, see the above document and MSDN.

If a driver supports orderly removal, and the device hardware can be disabled (that is, the device can be configured to stop accessing its assigned resources), then the ACPI namespace node for the device can include the Disable (_DIS ) object. This method will be evaluated by the operating system whenever the driver is removed. Use of _DIS has the following additional requirements:

·         _STA must clear the "enabled and decoding its resources" bit whenever the device is disabled.

·         The device must provide the Set Resource Settings (_SRS) object to re-enable the device hardware and set the above bit in _STA.

For more information, see sections 6.2.3 (_DIS), 6.2.15 (_SRS), and 6.3.7 (_STA) of the ACPI 5.0 specification.

2.3.6  Device Dependencies

Typically, there are hardware dependencies between devices on a particular platform. Windows requires all such dependencies be described so that it can ensure that all devices function correctly as things change dynamically in the system (device power is removed, drivers are stopped and started, and so on). In ACPI, dependencies between devices are described in the following ways:

1.       Namespace Hierarchy. Any device that is a child device (listed as a device within the namespace of another device) is dependent on the parent device. For example, a USB HSIC device is dependent on the port (parent) and controller (grandparent) it is connected to. Similarly, a GPU device listed within the namespace of a system MMU device is dependent on the MMU device.

2.       Resource Connections. Devices connected to GPIO or SPB controllers are dependent on those controllers. This type of dependency is described by the inclusion of Connection Resources in the device's _CRS.

3.       OpRegion Dependencies. For ASL control methods that use OpRegions to perform I/O, dependencies are not implicitly known by the operating system because they are only determined during control method evaluation. This issue is particularly applicable to GeneralPurposeIO and GenericSerialBus OpRegions in which Plug and Play drivers provide access to the region. To mitigate this issue, ACPI defines the Operation Region Dependency (_DEP) object. _DEP should be used in any device namespace in which an OpRegion (HW resource) is referenced by a control method, and neither 1 nor 2 above already applies for the referenced OpRegion's connection resource. For more information, see section 6.5.8, "_DEP (Operation Region Dependencies)", of the ACPI 5.0 specification.

There may also be software dependencies between device drivers. These dependencies must also be described. For more information, see the following resources:

?        For driver-load-order dependencies, see the "How To Control Device Driver Load Order" article at .

?        For power-relations dependencies, see:

o   The IoInvalidateDeviceRelations reference page at (To trigger establishing power relations, call the IoInvalidateDeviceRelations routine with the DEVICE_RELATION_TYPE enum value PowerRelations.)

o   The IRP_MN_QUERY_DEVICE_RELATIONS reference page at

o   The "Enumerating the Devices on a Bus" topic at 

o   The "Dynamic Enumeration" topic at

o   The WdfDeviceInitSetPnpPowerEventCallbacks reference page at 

2.4  General-Purpose I/O (GPIO)

SoCs make extensive use of general-purpose I/O (GPIO) pins. For SoC platforms, Windows defines a general abstraction for GPIO hardware, and this abstraction requires support from the ACPI namespace. The GPIO abstraction is supported by the ACPI 5.0 definitions listed in the following sections.

2.4.1  GPIO Controller Devices

Windows supports GPIO controllers. GPIO controllers provide a variety of functions for peripheral devices, including interrupts, input signaling, and output signaling. GPIO capabilities are modeled as a GPIO controller device in the namespace. The (GpioClx) models the GPIO controller device as being partitioned into some number of banks of pins. Each pin bank has 64 or fewer configurable pins. The banks in a GPIO controller are ordered relative to their pins' position within the controller-relative GPIO pin space. For example, bank 0 contains pins 0-31 on the controller, bank 1 contains pins 32-63, and so on. All banks have the same number of pins, except for the last bank, which might have fewer. Banks are significant for the ACPI firmware because the firmware must report the mapping of system interrupt resources to banks, as described in section 2.4.2.1 below.

Each pin on a bank has a set of parameters (for example, output, level-sensitive interrupt, de-bounced input, and so on) that describe how the pin is to be configured.

2.4.1.1  GPIO Controllers and ActiveBoth Interrupts

A feature of some GPIO controllers is the ability to generate interrupts on both edges of a signal (rising, or ActiveHigh edges, and falling, or ActiveLow edges). This is useful in a variety of applications, including the button interface, wherein both button-press events (one edge) and button-release events (the opposite edge) are meaningful. This feature is referred to as "ActiveBoth".

Logically, ActiveBoth signals have both an Asserted and Unasserted state, whether they are momentary assertions (for example, pushbuttons), or indefinitely long assertions (for example, headphone jack insertions). Edge detection for ActiveBoth interrupts might be implemented in the GPIO controller hardware (Hardware ActiveBoth), or be emulated in the GPIO driver software (Emulated ActiveBoth). Windows requires that GPIO controllers that implement ActiveBoth must use Emulated ActiveBoth. This is required to ensure robust handling of double-edged interrupts for all scenarios. In support of ActiveBothEmulation, the following hardware requirements apply:

1.       GPIO controllers that support ActiveBoth Interrupts must support level-mode interrupts, and support re-programming the polarity of the interrupt dynamically at run time.

2.       To minimize the risk of I/O errors, Windows prefers the use of memory-mapped GPIO controllers instead of SPB-connected GPIO controllers. In fact, for the Windows Button Array device (PNP0C40), it is required that the ActiveBoth GPIO interrupts for this device connect to a memory-mapped GPIO controller, and not to an SPB-connected one. To determine which button interrupts must be ActiveBoth, see section 2.8.7, "Button Devices", later in this paper.

3.       To establish a deterministic initial state for ActiveBoth interrupt signals, the Windows GPIO device stack guarantees that the first interrupt generated after connection of the interrupt by the driver will always be for the signal's asserted state. The stack further assumes that the asserted state of all ActiveBoth interrupt lines is logic level low (the ActiveLow edge) by default. If this is not the case on your platform, you can override the default by including the GPIO controller Device-Specific Method (_DSM) in the controller's namespace. For more information about this method, see Appendix A (section A.1, "GPIO Controller Device-Specific Method (_DSM)") later in this paper.

Note   Requirement 3 in the preceding list implies that the driver for a device that uses ActiveBoth might receive an interrupt immediately after initializing (connecting to) the interrupt, if the signal at the GPIO pin is in the asserted state at that time. This is possible, and even likely for some devices (for example, headphones), and must be supported in the driver.

To support emulated ActiveBoth, the GPIO controller driver must enable ("opt-in to") ActiveBoth emulation by implementing a callback function, and by setting the EmulateActiveBoth flag  in the basic information structure that the driver's callback function supplies to GpioClx. For more information, see the GPIO driver documentation on MSDN at .

2.4.2  GPIO Namespace Objects

GPIO controllers, and the peripherals that connect to them, are enumerated by ACPI. The connection between them is described using GPIO Connection Resource Descriptors. For more information, see section 6.4.3.8, "Connection Descriptors", of the ACPI 5.0 specification.

2.4.2.1  Device Identification and Configuration Objects

A GPIO controller device's ACPI namespace includes:

·         A vendor-assigned ACPI-compliant Hardware ID (_HID) object.

·         A set of resources consumed (_CRS) object.

·         A Unique ID (_UID) object, if there is more than one instance of the GPIO controller in the namespace (i.e., two or more namespace nodes with the same device identification objects).

The GPIO controller's _CRS contains all of the resources (address space for registers, system interrupts, and so on) consumed by all of the banks in the GPIO controller. The interrupt resource-to-bank mapping is represented in the order in which the interrupt resources are listed in the _CRS—that is, the first interrupt listed is assigned to bank 0, the next one listed is assigned to bank 1, and so on. Banks can share interrupt resources, in which case the interrupt is listed once for each bank connected to it, in bank order, and is configured as Shared.

2.4.2.2  GPIO Connection Resource Descriptors

The relationship between peripherals and the GPIO pins to which they are connected is described to the operating system by GPIO Connection Resource Descriptors. These resource descriptors can define two types of GPIO Connections:  GPIO Interrupt Connections and GPIO IO Connections. Peripherals include GPIO Connection descriptors in their _CRS for all GPIO I/O and interrupt pins connected. If a connected interrupt is wake-capable (capable of waking the system from a low-power idle state; see section 2.6, "Device Power Management", later in this paper), then it must be configured as ExclusiveAndWake or SharedAndWake.

The descriptors are defined in section 6.4.3.8.1, "GPIO Connection Descriptor", of the ACPI 5.0 specification. The ASL Resource Template Macros for these descriptors are described in section 19.5.53, "GpioInt (GPIO Interrupt Connection Resource Descriptor Macro)", of the ACPI 5.0 specification.

2.4.2.3  GPIO-Signaled ACPI Events

ACPI defines a platform event model that enables hardware events in the platform to be signaled and communicated to the ACPI driver. Windows provides a Notification service for communicating platform events to device drivers. A number of inbox drivers rely on this mechanism to provide support for ACPI-defined devices, such as Control Method Power Button, LID device, Control Method Battery, Thermal Zone, and so on. For more information about notifications, see section 5.6.5, "GPIO-Signaled ACPI Events", of the ACPI specification.

For SoC platforms, GPIO interrupts are used to signal platform events. Any namespace device ("ACPI Event Source" device) that signals events to its driver using the ASL notify operator, requires:

·         The namespace node of the GPIO controller to which the ACPI event signal is connected must include a GpioInt resource for that pin in its ACPI Event Information (_AEI) object (see section 2.4.2.3.1,  "ACPI Event Information (_AEI) Object", below). The GpioInt resource must be configured as non-shared (Exclusive).

·         The controller's node must also contain an Edge (_Exx), Level (_Lxx) or Event (_EVT) control method for each pin listed in the _AEI object.

The ACPI driver handles the listed GPIO interrupt and evaluates the Edge, Level or Event control method for it. The control method quiesces the hardware event, if necessary, and executes the required Notify operator on the event source device's namespace node. Windows then sends the notification to the device's driver. Multiple events can be signaled over the same GpioInt resource if the event control method can query the hardware to determine which event occurred. The method must then notify the correct device with the correct notification code.

2.4.2.3.1  ACPI Event Information (_AEI) Object

As mentioned above, the GPIO controller's namespace must contain the _AEI object in order to support ACPI events. The _AEI object (see section 5.6.5.2 in the ACPI 5.0 specification) returns a Resource Template buffer containing only GpioInt descriptors that signal ACPI events via this GPIO controller. Each descriptor corresponds to one ACPI event source device and is dedicated to that device (not shared between devices).

2.4.2.4  GeneralPurposeIO Operation Regions (OpRegions)

GPIO controllers are often used by platform firmware to support any number of platform hardware features such as controlling power and clocks, or setting modes on devices. To support the use of GPIO I/O from ASL control methods, ACPI 5.0 defines a new Operation Region type, "GeneralPurposeIO".

GeneralPurposeIO Operation regions (see section 5.5.2.4.4 of the ACPI 5.0 specification) are declared within the namespace scope of the GPIO controller device whose driver will handle the I/O. GeneralPurposeIO Field declarations (see section 5.5.2.4.4.1 of the ACPI 5.0 specification) assign names to GPIO pins that are to be accessed within a GeneralPurposeIO OpRegion. GpioIO Connection Resources (see section 19.5.53 of the ACPI 5.0 specification) are used within the Field declaration to specify the pin number(s) and configuration for a particular Field reference. The total number of named field bits following a connection descriptor must equal the number of pins listed in the descriptor.

Fields in an OpRegion can be declared anywhere in the namespace and accessed from any method in the namespace. The direction of accesses to a GeneralPurposeIO OpRegion is determined by the first access (read or write) and cannot be changed.

Note  Because OpRegion access is provided by the GPIO controller device driver (the "OpRegion Handler"), methods must take care not to access an OpRegion until the driver is available. ASL code can track the state of the OpRegion handler by including a Region (_REG) method under the GPIO controller device (see section 6.5.4 of the ACPI 5.0 specification). Additionally, the OpRegion Dependencies (_DEP) object (see section 6.5.8 of the ACPI 5.0 specification) can be used under any device that has a method accessing GPIO OpRegion fields, if needed. See the section on Dependencies, above, for a discussion of when to use _DEP.

It is important that drivers are not assigned GPIO I/O resources that are also assigned to GeneralPurposeIO OpRegions. Opregions are for the exclusive use of ASL control methods.

To verify that your GPIO controller meets all Windows platform requirements, see Appendix B, "GPIO Controller Requirements Checklist", later in this paper.

2.5  Simple Peripheral Bus (SPB)

SoCs make extensive use of simple, low-pin-count and low-power serial interconnects for connecting to platform peripherals. I2C, SPI and UARTs are examples. For SoC platforms, Windows provides a general abstraction for SPB hardware, and this abstraction requires new support from the ACPI namespace.

2.5.1  SPB Controller Devices

A SPB controller device is identified in the namespace with a vendor-assigned Hardware ID (_HID) and a set of resources consumed (_CRS).

2.5.2  SPB Namespace Objects

2.5.2.1  SPB Resource Descriptors

As with GPIO connections, SPB connections are described to the operating system by the consuming device, via new resource descriptors. The Generic Serial Bus Resource Descriptor is used to declare I2C connections, SPI connections, and UART connections, and is extensible to support other serial bus types in the future.

Resource Template Macros for these descriptors are described in section 19.5.55, "I2CSerialBus (I2C Serial Bus Connection Resource Descriptor Macro) ", of the ACPI 5.0 specification.

2.5.2.2  GenericSerialBus Operation Regions

Also similar to GPIO, ACPI 5.0 defines an Operation Region for use with SPB controllers, GenericSerialBus (section 5.5.2.4.5 of the ACPI 5.0 specification). Because SPBs are communication buses,  GenericSerialBus OpRegions support various protocols for accessing SPB target devices. For more information, see section 5.5.2.4.5.3, "Using the GenericSerialBus Protocols", of the ACPI 5.0 specification.

Often with SPBs, it is necessary for ASL control methods to share access to a SPB target device with the operating system driver for that device. To ensure synchronization of these accesses, ACPI 5 defines the Device Lock Mutex (_DLM) object. For more information, see section 5.7.5 of the ACPI 5.0 specification.

2.6  Device Power Management

2.6.1  Device Power Management in Windows

While a system is running (that is, the system is in the ACPI-defined working state, S0), individual devices can make transitions between device power states, depending on activity, to save power. In traditional PC systems, ACPI-defined sleeping states (S1 through S4) are also used to save power, but these disconnected, high-latency sleep states are not used on Windows SoC platforms. Therefore, battery life is highly dependent on how platforms implement run-time device power management.

Devices integrated into the SoC can be power-managed through the Windows Power Framework (PoFx). These framework-integrated devices are power-managed by PoFx through a SoC-specific power engine plug-in (microPEP) that knows the specifics of the SoC's power and clock controls. For more information about PoFx, see on MSDN.

For peripheral devices that are not integrated into the SoC, Windows uses ACPI Device Power Management. For these ACPI-managed devices, the power policy owner in a device driver stack (typically the function or class driver) makes device power state transition decisions, and the ACPI driver invokes ASL control methods to apply the required platform-specific power controls.

Note   It is possible to, and some device stacks do, use ACPI Device Power Management—alone, or in combination with the microPEP—for on-SoC device power management.

As described in the following paragraphs, Windows supports the D3cold power management capabilities defined in the ACPI 5.0 specification. With this support, devices, platforms and drivers can opt-in to having device power completely removed during run-time idle periods. This capability can significantly improve battery life. However, removing power must be supported by all affected components in order to be able to return to D0 successfully. For this reason, drivers (bus and function), as well as the platform itself, must indicate that they support it. For more information about D3cold driver opt-in, see on MSDN.

2.6.2  Device Power Management in ACPI

Namespace devices support up to four device power states, numbered D0 (full-function, or "on") to D3 (no function, or "off"). Each state can have different power requirements, with higher-numbered states consuming less power than lower-numbered states. Further, the D3 (off) state has two sub-states, D3hot and D3cold. The D3hot sub-state requires the device to remain accessible on its parent bus so that it can respond to bus-specific software commands. This requirement, and the power used to meet it, are removed in D3cold. Finally, a device can be armed to wake itself from a low-power state due to a hardware event, and, if necessary, to also bring the platform out of an idle state.

The platform indicates its support for D3cold by granting the OS control of the "_PR3 Support" feature (bit 2) when requested via the platform-wide OSPM Capabilities Method. See section 6.2.10.2, “Platform-wide OSPM Capabilities”, in the ACPI 5.0 specification.

Power-managed devices use child objects to describe their power capabilities to the operating system. The following sections describe these capabilities and objects.

2.6.2.1  Power Resources and States

A device declares its support for a power state by listing the set of power resources it requires in order to be in that state. ACPI Power Resources represent the voltage rails that power devices and the clock signals that drive them. These resources are declared at the root of the namespace. Each power resource has an _ON and an _OFF method through which it is controlled, and an _STA method to report its state. For more information, see section 7.1, "Declaring a Power Resource Object", of the ACPI 5.0 specification.

The operating system's ACPI driver monitors the power dependencies among devices that share resources, and, as these devices transition between power states, ensures that only the power resources that are actually needed by a device are turned on at any particular time.

2.6.2.1.1  Power Resource Requirements (_PRx)

There is a Power Resource Requirements (_PRx) object, where x = 0, 1, 2, or 3, for each supported device power state. When the device driver decides to transition to a new power state, the ACPI driver ensures that any power resources required for the new state are turned on, and that any resources no longer in use are turned off.

Device state supported	Resource requirements object to use	Resources to include in requirements object
D0 (Required)	_PR0	All power and clocks required for full function of the device.
D1	_PR1	Any power or clocks required for the class-defined reduced-functionality of this state.
D2	_PR2	Any power or clocks required for the class-defined reduced-functionality of this state.
D3hot (Required)	_PR2	The same resources as the next higher state that is supported (D2, D1 or D0).
D3cold	_PR3	Only the power or clocks required for the device to appear on its bus and respond to a bus-specific command.

Note  If a particular platform supports the D3cold feature, and the device driver for a device opts-in to D3cold, the device's _PR3 power resources will, if they are not being used by any other device, be turned off sometime after the transition to D3hot.

2.6.2.1.2  Device Power State (_PSx)

There is a Power State method, _PSx, where x = 0, 1, 2, or 3, for each supported device power state Dx. This method is optional, but if it is present it is invoked before the power resources for the state are turned off, and after the power resources for the state are turned on. _PSx is intended to perform any platform-specific actions required around the power cycle. _PSx must not access device registers that are assigned to the function driver, access bus-standard registers that are assigned to the bus driver, or switch power resources on or off, which is an operation reserved for the ACPI driver.

2.6.2.2  Wake Capabilities

Power-managed devices might be able to detect events when in a low-power state and cause the platform to wake up to handle them. To enable this feature, Windows needs information about the capabilities of both the platform and the device.

2.6.2.2.1  Sx Device Wake State (_SxW)

On a given platform, there is a specific mapping between device states that support the wake capability and system states that can respond to wake events. ACPI defines the _SxW object to provide this information to the operating system. There is an SxW object for each supported system power state, Sx. Since SoC platforms are always in S0, the only object of interest here is _S0W. This object specifies the platform's ability to wake from a low-power idle state in response to a device's wake signal. The object is used by Windows to determine the target D-state for the device during system low-power idle. For more information about _S0W, see section 7.2.20, "_S0W (S0 Device Wake State)", in the ACPI 5.0 specification.

For most SoC platforms, devices are aggressively power-managed to the D3 state when idle, and the system is capable of waking from low-power idle while the device is in this state. For such a system, the _S0W object returns 3 (or 4, if it also supports D3cold). However, any D-state can be designated as the lowest-powered wake- capable state, and some device classes or buses use different values. For instance, SDIO- and USB-connected devices use state D2 for this state.

Note  To facilitate the migration of device drivers from Windows 7 to Windows 8, your device might be required to supply _S4W as well. At this time, the only device class that requires this is networking (Ndis.sys).

2.6.2.2.2  Wake-Capable Interrupts (_CRS)

The resource description for a device indicates that the device is capable of detecting and signaling a wake event by marking an interrupt as "wake-capable" (either ExclusiveAndWake or SharedAndWake). Windows and device drivers provide special handling of such interrupts to ensure that they are enabled when the device transitions to a low-power state. For more information, see the descriptions of the Interrupt and GpioInt resource descriptors in section 6.4.3.6, "Extended Interrupt Descriptor", and section 6.4.3.8.1 , "GPIO Connection Descriptors", of the ACPI 5.0 specification.

2.6.2.3  Wake Enablement

Depending on user scenario or system policy, wake-capable devices may or may not actually be armed for wake. Therefore, wake-capable interrupts may or may not be enabled when the device is idle. In addition to enabling interrupts, Windows uses the following mechanisms to enable wake on a device.

2.6.2.3.1  Device Sleep Wake (_DSW)

ACPI defines the _DSW object as a way for the operating system to inform the ACPI platform firmware about the next sleep or low-power idle period. This object is optional, and is used only if the platform has a need to configure platform-specific wake hardware in advance. The target D-state for the device and the target S-state for the system are both provided. The D-state and S-state combination will always comply with the information provided by the device's _SxW object(s).

2.6.2.3.2  Power Resources for Wake (_PRW)

In some cases, there are additional power resources that must be turned on for a device to be enabled for wake. In this case, the device can provide the _PRW object to list those additional power resources. The operating system's ACPI driver will manage these power resources as it does normally, making sure they are turned on when they are needed by a device (that is, a wake-enabled device), and are turned off otherwise.

_PRW is also used to define the wake capability for traditional (full-ACPI hardware) PC platforms.

2.7  ACPI-Defined Devices

ACPI defines a number of devices to represent and control typical platform features. Examples are a power button, a sleep button, system indicators, and so on. For more information, see section 9, "ACPI-Defined Devices and Device-Specific Objects", of the ACPI 5.0 specification. For the target SoC platforms, the ACPI-defined devices described in the following sections are supported by built-in drivers.

2.7.1  Lid Device

This device describes and reports the status of a clamshell device's lid. For more information, see section 9.4, "Control Method Lid Device", of the ACPI 5.0 specification. Lid device implementations use the GPIO-signaled ACPI event mechanism, which is described in section 5.6.5, "GPIO-Signaled ACPI Events", of the ACPI 5.0 specification.

2.7.2  Control Method Battery Device

This device describes, configures, and reports the status of the platform battery. For more information, see section 10.2, "Control Method Batteries", of the ACPI 5.0 specification. Control Method Battery implementations on SoC platforms use the GPIO-signaled ACPI event mechanism, which is described in section 5.6.5, "GPIO-Signaled ACPI Events", of the ACPI 5.0 specification. Access to the battery and charging hardware is done by methods that operate through GPIO or SPB OpRegions, which are described in sections 5.5.2.4.4 and 5.5.2.4.5 of the ACPI 5.0 specification.

For more information about battery management in Windows, see the "Windows Power and Battery Subsystem Requirements" white paper at .

2.7.2.1  Battery Device-Specific Method

To support the passive thermal management of the battery by the platform, Microsoft defines a _DSM method to communicate to the platform firmware the thermal throttling limit set by the battery's thermal zone. For more information, see the following:

·         Appendix A (section A.2, "Battery Device-Specific Method") later in this paper.

·         Section 2.7.4, "Thermal Zones", below.

2.7.3  Control Method Time and Alarm Device

ACPI 5 defines the operation and definition of the optional control method-based Time and Alarm device, which provides a hardware-independent abstraction and a more robust alternative to the Real Time Clock (RTC). For more information, see section 9.15, "PC/AT RTC/CMOS Devices", and section 9.18, "Time and Alarm Device", of the ACPI 5.0 specification. If the standard PC RTC either is not implemented or is used as the RTC hardware backing the Time and Alarm device, the "CMOS RTC Not Present" bit of the FADT's Boot Architecture flags field must be set.

The time capabilities of the Time and Alarm device are required for platforms that support the InstantGo feature (and the Connected Standby power mode). These capabilities maintain time-of-day information across system power transitions, and keep track of time even when the platform is turned off. It is expected that the time on the platform will be consistent when different firmware interfaces are used to query the platform time. For example, a UEFI call to get the time should return the same time that the operating system would get by using the Time and Alarm device.

The Time and Alarm device must be driven from the same time source as UEFI time services.

2.7.4  Thermal Zones

2.7.4.1  Thermal Management in Windows

The Windows thermal management model is based on ACPI's concept of thermal zones. This is a cooperative firmware/OS/driver model that abstracts the sensors and cooling devices from the central thermal management component through well-defined interfaces. For more information about thermal management, see the document titled "Thermal Management in Windows" on the Microsoft Connect website at .

2.7.4.2  ACPI Thermal Zones

A thermal zone is defined to include child objects that do the following:

?        Identify the devices contained in the thermal zone:

o   _TZD to list the non-processor devices in the thermal zone.

o   _PSL to list the processors in the thermal zone.

?        Specify thermal thresholds at which actions must be taken:

o   _PSV to indicate the temperature at which the operating system starts passive cooling control.

o   _HOT to indicate the temperature at which the operating system hibernates.

o   _CRT to indicate the temperature at which the operating system shuts down.

?        Describe the thermal zone's passive cooling behavior:

o   _TC1, _TC2 for thermal responsiveness.

o   _TSP for the appropriate temperature sampling interval for passive cooling of the thermal zone.

?        Report the thermal zone's temperature:

o   _TMP for firmware-reported temperature, or

o   _HID and _CRS for loading a temperature sensor driver and allocating hardware resources to it.

?        Optionally, receive notifications of additional temperature threshold crossings:

o   _NTT for specifying additional threshold crossings to be notified of.

o   _DTI for receiving notifications of additional threshold crossings.

?        Optionally, describe the thermal zone's Active Cooling Behavior:

o   _ALx for listing the fans in the thermal zone.

o   _ACx the temperature at which fan x must be turned on.

For more information about ACPI thermal zones, see chapter 11, "Thermal Management", of the ACPI 5.0 specification.

2.7.4.3  Logical Processor Idling as a Thermal Mitigation

The platform can indicate to the operating system that processor cores in the thermal zone should be idled (instead of throttled). This is done by including the Processor Aggregator device (ACPI000C) in one or more thermal zones. Windows will park a number of cores when the thermal zone's _PSV is crossed. The number is either

(1 - zone_passive_limit) * (the number of cores in the thermal zone),

or the number of cores reported in _PUR, whichever is greater. For more information, see section 8.5.1, "Logical Processor Idling", in the ACPI 5.0 specification.

OEMs can include a Device-Specific Method (_DSM) to support the Microsoft thermal extensions for Windows. For more information, see Appendix A (section A.3, "Device-Specific Method for Microsoft Thermal Extensions") later in this paper.

2.8  Other Namespace Objects

For some specific classes of device, there are requirements for additional namespace objects to appear under those devices in the namespace. This section lists those for SoC platforms.

2.8.1  Processor Identification Objects

Processors must be enumerated in the ACPI namespace. Processors are declared under \_SB using the "Device" statement, as with other devices on the platform. Processor devices must contain the following objects:

?        _HID : ACPI0007

?        _UID: A unique number that matches the processor's entry in the MADT.

2.8.2  Display-Specific Objects

For more information about display-specific objects, see Appendix B, "Video Extensions", of the ACPI 5.0 specification.

Display-Specific Object Requirements

Method	Description	Requirement
_DOS	Enable/Disable output switching.	Required if system supports display switching or LCD brightness levels.
_DOD	Enumerate all devices attached to display adapter.	Required if integrated controller supports output switching.
_ROM	Get ROM Data.	Required if ROM image is stored in proprietary format.
_GPD	Get POST Device.	Required if _VPO is implemented.
_SPD	Set POST Device.	Required if _VPO is implemented.
_VPO	Video POST Options.	Required if system supports changing post VGA device.
_ADR	Return the unique ID for this device.	Required
_BCL	Query list of brightness control levels supported.	Required if embedded LCD supports brightness control.
_BCM	Set the brightness level.	Required if _BCL is implemented
_DDC	Return the EDID for this device.	Required if embedded LCD does not support return of EDID via standard interface.
_DCS	Return status of output device.	Required if the system supports display switching (via hotkey).
_DGS	Query graphics state.	Required if the system supports display switching (via hotkey).
_DSS	Device state set.	Required if the system supports display switching (via hotkey).

2.8.3  USB Host Controllers and Devices

USB host controllers are used on SoC platforms for connecting internal and external devices. Windows includes inbox drivers for standard USB host controllers that are compliant with the EHCI or XHCI specifications.

On SoC platforms, the USB host controller can be enumerated by ACPI. Windows uses the following ACPI namespace objects when enumerating and configuring compatible USB hardware:

?        A vendor-assigned ACPI-compliant Hardware ID (_HID).

?        A Unique ID (_UID) object, if there is more than one instance of the USB controller in the namespace (that is, two or more nodes that have identical device identification objects).

?        A Compatible ID (_CID) for the EHCI or XHCI Standard-compliant USB host controller (EHCI: PNP0D20), (XHCI: PNP0D10).

?        The Current Resource Settings (_CRS) assigned to the USB controller. The controller's resources are described in the appropriate hardware interface specification (EHCI or XHCI).

2.8.3.1  USB Device-Specific Method (_DSM)

Windows defines a Device-Specific Method (_DSM) to support device-class-specific configuration of the USB subsystem. For more information, see Appendix A (section A.4, "USB Device-Specific Method") later in this paper.

2.8.3.2  USB Integrated Transaction Translator (TT) Support (_HRV)

Standard EHCI host controllers only support high-speed USB devices. On SoC platforms, Windows supports two common designs of EHCI-compliant host controllers which implement an integrated transaction translator for low-speed and full-speed USB devices. The Hardware Revision (_HRV) object indicates the type of integrated TT support to the USB host controller driver.

The _HRV is set according to the following criteria:

?        NoIntegratedTT - _HRV = 0

o   Standard EHCI host controllers do not implement integrated transaction translators, and an _HRV value of 0 is only valid for these controllers. It is not necessary to include the _HRV object for these controllers.

?        IntegratedTTSpeedInPortSc - _HRV = 1

o   Enable integrated TT support. This flavor of interface includes the LowSpeed and HiSpeed bits in the PORTSC register itself. These bits are at bit offsets 26 and 27, respectively. When determining the speed, the EHCI driver will read the PORTSC, and extract the speed information from these bits.

?        IntegratedTTSpeedInHostPc - _HRV = 2

o   Enable integrated TT support. This flavor of interface includes the LowSpeed and HiSpeed bits in a separate HOSTPC register. When the EHCI driver needs to determine the port speed, it will read the HOSTPC register corresponding to the port of interest and extract the speed information.

2.8.3.3  USB XHCI D3cold Support

In addition to selective suspend, internal USB devices connected to XHCI controllers can be put into a D3cold state and powered off when not in use (see section 2.6, "Device Power Management", earlier in this paper). All USB device function drivers must opt-in to D3cold.

2.8.3.4  USB Port-Specific Objects

Windows needs to know the visibility and connect-ability of USB Ports on the system. This is required in order to provide accurate information to the user about ports and devices. Two objects, Physical Device Location (_PLD) and USB Port Capabilities (_UPC), are used for this purpose. For more information, see the following:

·         Sections 6.1.6, "Device Identification Objects", and 9.13.1, "USB 2.0 Host Controllers and _UPC and _PLD", of the ACPI 5.0 specification

·         The topic on MSDN

2.8.4 SD Host Controllers and Devices

SD Host controllers are used on SoC platforms for access to storage as well as IO devices. Windows includes an inbox driver for SDA-standard host controller hardware. For compatibility with this driver, an SD Host Controller device must be compliant to the SD Association's SD Host Controller Specification.

On SoC platforms, the SD host controller can be enumerated by ACPI. Windows uses the following ACPI Namespace objects when enumerating and configuring compatible SD Hardware:

?        A vendor-assigned ACPI-compliant Hardware ID (_HID).

?        A Unique ID (_UID) object, if there is more than one instance of the SD controller in the namespace (that is, two or more nodes that have identical device identification objects).

?        A Compatible ID (_CID) for the SDA standard-compliant SD host controller (PNP0D40).

?        The Current Resource Settings (_CRS) assigned to the controller. The controller's resources are described as follows:

o   Hardware resources for all implemented slots are included. A slot is a connection point on the SDIO bus for a memory or I/O device. Each slot is associated with a standard set of registers and an interrupt in the SD host controller, which are used for communication with the connected device. SD host controllers may implement any number of slots, but on SoC platforms, there is typically only one.

o   Slot resources are listed together, in order of slot number (slot 0's resources are first, slot 1's resources are second, and so on).

o   For each slot, resources are listed in the following order:

§  The base address of the SD standard register set for the slot

§  The SD standard interrupt for the slot

§  A GPIO interrupt resource for the slot, for signaling card insertions and removals (if the standard SD card-detect interface is not supported during all power states).

§  A GPIO input resource for the slot for reading whether a card is currently in the slot (if the standard SD card-detect interface is not supported during all power states). Uses the same pin as the insertion/removal interrupt.

§  A second GPIO input resource for reading whether the card in the slot is write-protected (if the standard SD write-protect interface is not supported during all power states).

The interrupts must be wake-capable (described as "SharedAndWake" or "ExclusiveAndWake").

2.8.4.1  Embedded SD Devices

SD-connected devices are enumerated by the SD bus driver. SD devices that are integrated into the platform must also be listed in the ACPI namespace as children of the SD host controller. This requirement enables the operating system to associate the bus-enumerated device with the platform-specific attributes provided for the device by ACPI objects (for example, non-removability, device power states, GPIO or SPB resources consumed, and so on). To make this association, the device namespace requires the Address (_ADR) object, which communicates the address of the device on the SDIO bus. The _ADR object returns an integer. For the SDIO bus, the value of this integer is defined as follows.

SDIO bus

High word – Slot number (0–First Slot) Low word – Function number (See SD specification for definitions.)

An embedded SD device namespace must also include:

?        A Remove method (_RMV) object that returns 0 (to indicate that the device cannot be removed).

?        A _CRS object for the sideband resources the device requires (such as GPIO pins or SPB connections), if any are required.

2.8.5  Imaging Class Devices (Cameras)

Camera devices may be enumerated by the graphics driver or by USB. In either case, Windows needs to know the physical location of the camera so that the appropriate UI can be shown. To do this, camera devices that are built into the chassis of the system and have mechanically fixed direction, are included in the ACPI namespace and provide the Physical Device Location (_PLD) object. This requires:

?        The camera device to appear as a child (nested device) of the enumerator device (either the GPU device or the USB device).

?        The camera device to provide the Address (_ADR) object that contains the camera's address on the parent device's bus.

o   For USB, see section 2.8.5.1, "ACPI Namespace Hierarchy and _ADR for Embedded USB Devices", below.

o   For graphics, this is the identifier specified in the _DOD method provided under the GPU device. For more information, see Appendix B, "Video Extensions", of the ACPI 5.0 specification.

?        The camera device to provide the _PLD object.

?        If there are any sideband resources required by the camera driver (such as GPIO interrupt or I/O connections, or an SPB connection), the _CRS object is provided for these resources.

In the _PLD object, the Panel field (bits 67-69), Lid field (bit 66) and Dock field (bit 65) are set to correct values for the surface on which the camera is mounted. All other fields are optional. For handheld mobile devices, including tablets, the front panel is the one holding the display screen, and its origin is in the lower-left corner when the display is viewed in the portrait orientation. Using this reference, "Front" indicates that the camera views the user (webcam), while "Back" indicates that the camera views away from the user (still or video camera). For more information, see, section 6.1.8, "_PLD (Physical Location of Device)", of the ACPI 5.0 specification.

2.8.5.1  ACPI Namespace Hierarchy and _ADR for Embedded USB Devices

When adding embedded USB devices to the ACPI namespace, the hierarchy of the device nodes must exactly match that of the devices enumerated by the Windows USB driver. This can be determined by examining Windows Device Manager in its "View by Connection" mode. The entire hierarchy, starting from the USB host controller and extending down to the embedded device, must be included. The "Address" property provided in Device Manager for each device is the address that the firmware must report in the device's _ADR.

The ACPI 5.0 specification defines the addresses for USB devices as follows.

USB Root HUB	Only child of the host controller. It must have an _ADR of 0. No other children or values of _ADR are allowed.
USB Ports	Port number (1-n)

USB devices connected to a particular port share the address of that port.

If the device connected to a port is a composite USB device, functions within the composite device must use the following address.

USB function within a Composite USB device

Port number of the port to which the Composite device is connected, PLUS the first Interface number of the function. (Arithmetic addition).

For more information, see the "Windows 8 Requirement: Identifying the Location of Internal Cameras" white paper at .

2.8.5.2  Examples

2.8.5.2.1  A USB Webcam connected directly to USB Port 3

Device (EHCI) {

    ...  // Objects required for EHCI devices

    Device {RHUB) {               // the Root HUB

        Name (_ADR, ZERO)         // Address is always 0.

        Device (CAM0) {            // Camera connected directly to USB

                                  //   port number 3 under the Root.

            Name (_ADR, 3)        // Address is the same as the port.

            Method (_PLD, 0, Serialized) {...}

            }  //  End of Camera device

    } // End of Root Hub Device

}  // End of EHCI device

2.8.5.2.2  A USB Composite device that implements a Webcam as Function 2

Device (EHCI) {

    ...  // Objects required for EHCI devices

    Device {RHUB) {

        Name (_ADR, ZERO)

        Device (CUSB) {           // Composite USB device

                                  //   connected to USB port number 3

                                  //   under the Root.

            Name (_ADR, 3)        // Address is the same as the port.

            Device (CAM0) { // Camera function within the

                                  //   Composite USB device.

                Name (_ADR, 5)    // Camera function has a first

                                  //   Interface number of 2, so

                                  //   Address is 3 + 2  = 5.

                Method (_PLD, 0, Serialized) {...}

            }  //  End of Camera device

        } // End of Composite USB Device

    } // End of Root Hub Device

}  // End of EHCI device

2.8.5.2.3  A Webcam connected over I2C

Device (GPU0) {

    ... // Other objects required for graphics devices

    Name (_DOD, Package () // Identifies the children of this                                   //   graphics device.

                           // Each integer must be unique within the

                           //   GPU0 namespace.

                {

                    0x00024321,  // The ID for CAM0. It is a non-VGA

                                  //   device, cannot be detected by

                                  //   the VGA BIOS, and uses a vendor-

                                  //   specific ID format in bits 15:0

                                  //   (see the _DOD specification).

                    ...           // Other child device IDs (for

                                  //   example, display output ports)

                })

    Device (CAM0) {

        Name (_ADR, 0x00024321)   // The identifier for this device

                                  //   (Same as in _DOD above)

        Name (_CRS, ResourceTemplate()

            {

                     // I2C Resource

                     // GPIO interrupt resource(s), if required by

                     //   driver

                     // GPIO I/O resource(s), if required by driver

                ...

            })

        Method (_PLD, 0, Serialized) {...}

    } // End of CAM0 device

} // End of GPU0 device

2.8.6  HID-over-I2C Devices

Windows includes a class driver for Human Interface Devices (HID). This driver enables generic support for a broad range of input devices (such as touch panels, keyboards, mice, and sensors). On SoC platforms, HID devices can be connected to the platform over I2C, and are enumerated by ACPI. For compatibility with the HID class support in Windows, the following namespace objects are used:

?        A vendor-specific _HID

?        A _CID of PNP0C50

?        A _CRS with:

o   An I2CSerialBusConnection resource for access to the device

o   A GpioInt resource for interrupt(s)

?        The HIDI2C _DSM method for returning the HID Descriptor Register address within the device. For more information, see Appendix A (section A.5, " HIDI2C Device-Specific Method (_DSM)", later in this paper.

2.8.7  Button Devices

For SoC platforms, Windows supports both the ACPI-defined Control Method Power Button, as well as a Windows-compatible five-button array. The power button, whether implemented as an ACPI Control Method Power Button or as part of the Windows-compatible Button Array, does the following:

?        Causes the platform to power-up if it is off.

?        Generates the Power Button Override event when held down. For more information, see section 4.8.2.2.1.3, "Power Button Override", of the ACPI 5.0 specification.

2.8.7.1  Control Method Power Button

Clamshell designs, and other systems with built-in or connected keyboards, implement the ACPI-defined Control Method Power Button (section 4.8.2.2.1.2 of the ACPI 5.0 specification) using GPIO-Signaled ACPI Events (section 5.6.5 of the ACPI 5.0 specification). To support the power button device, the namespace:

?        Describes the power button's GPIO interrupt pin as a non-shared (Exclusive) GPIO interrupt resource.

?        Lists the power button's GPIO interrupt resource in the _AEI object of the GPIO controller to which it is connected.

?        Provides the associated event method (Lxx/Exx/EVT) under the GPIO controller device. This event method notifies the Control Method Button driver in the operating system that the button event has occurred.

For more information, see the "Hardware Buttons for Windows 8 Tablet and Convertible Devices" white paper at .

2.8.7.2  Windows-Compatible Button Array

For touch-first (keyboard-less) platforms, such as slates, Windows provides a generic driver for an array of five buttons. Each button in the array has its defined function (see the numbered items in the list below), and certain "hold-and-press" button combinations have additional meaning in the UI. No button combinations are defined that require the power button to be held down. For compatibility with the Windows inbox button driver, the Windows-compatible Button Array ACPI device is implemented. The device is defined as follows:

?        Each of the five buttons is connected to its own dedicated interrupt pin on the platform.

?        Each interrupt pin is configured as a non-shared (Exclusive), edge-triggered (Edge) interrupt resource that interrupts on both edges (ActiveBoth).

?        The device namespace contains a vendor-defined _HID as well as a _CID of PNP0C40.

?        The GPIO interrupt resources in the _CRS object are listed in the following order:

1.       Interrupt corresponding to the "Power" button

§  The "Power" button must be wake-capable (ExclusiveAndWake).

2.       Interrupt corresponding to the "Windows" button

§  The Windows button must be wake-capable (ExclusiveAndWake).

3.       Interrupt corresponding to the "Volume Up" button

§  The "Volume Up" button must not be wake-capable (must use Exclusive).

4.       Interrupt corresponding to the "Volume Down" button

§  The "Volume Down" button must not be wake-capable (must use Exclusive).

5.       Interrupt corresponding to the "Rotation Lock" button, if supported

§  The "Rotation Lock" button must not be wake-capable (must use Exclusive).

For more information, see the "Hardware Buttons for Windows 8 Tablet and Convertible Devices" white paper at .

To support evolution of the Windows Button UI, Windows defines a Device-Specific Method (_DSM) for the Windows Button Array device. For more information, see Appendix A (section A.6, "Windows Button Array Device-Specific Method (_DSM)", later in this paper.

2.8.8  Dock and Convertible PC Sensing Devices

Windows supports docks and convertibles (clamshell/tablet combos) by the use of two sensing devices in the ACPI namespace. These devices are supported by the Windows inbox button driver. Note that the same requirements that apply to the Button Array device also apply to these devices:

?        GPIO ActiveBoth interrupts must be connected to an on-SoC GPIO controller (not to an SPB-connected GPIO controller).

?        The GPIO controller must support level-mode interrupts and dynamic polarity reprogramming.

?        The GPIO controller driver must use ActiveBoth emulation provided by the (GpioClx).

?        If the asserted state ("Docked" or "Converted") is not asserted logic level low, the GPIO controller _DSM method is required to override the GPIO driver stack's default behavior. For more information, see section 2.4.1, "GPIO Controller Devices", earlier in this paper.

For more information about the inbox button driver, see the "Hardware Buttons for Windows 8 Tablet and Convertible Devices" white paper at .

2.8.8.1  Dock Sensing Device

This device interrupts the system when a dock is attached or unattached from the system. This mode change information is used to update the user input and output experience, as required. The device's namespace requires:

?        A vendor-specific _HID

?        A _CID of PNP0C70

?        A _CRS with one ActiveBoth interrupt

o   Interrupt cannot be wake-capable.

2.8.8.2  Convertible PC Sensing Device

This device interrupts the system when a convertible PC switches from tablet to clamshell form factor. This mode change information is used to update the user input and output experience, as required. The device's namespace requires:

?        A vendor-specific _HID

?        A _CID of PNP0C60

?        A _CRS with one ActiveBoth interrupt

o   Interrupt cannot be wake-capable.

Appendix A: Device-Specific Methods

This appendix defines the device-specific methods discussed in this paper.

A.1  GPIO Controller Device-Specific Method (_DSM)

As a means of supporting a variety of device-class-specific communications between the GPIO driver stack and the platform, Microsoft defines a Device-Specific Method (_DSM) that can be included under a GPIO controller in the ACPI namespace. Currently, this method defines two functions:

·         Function Index 0: The Standard Query Function that all _DSM methods are required to provide.

·         Function Index 1: The ActiveBoth Polarity Function, which informs the GPIO stack of any ActiveBoth pins on the controller that are not asserted logic low. The GPIO Stack assumes that ActiveBoth Pins are asserted logic low, so this function allows the platform to override that default for specific pins.

A.1.1  Definition

The GUID for the GPIO controller _DSM method is defined to be:

{4F248F40-D5E2-499F-834C-27758EA1CD3F}

A.1.2  Function 0

Function 0 of every _DSM is a query function that returns the set of supported function indexes, and is always required. For the definition of Function 0, see section 9.14.1, "_DSM (Device Specific Method)", of the ACPI 5.0 specification.

A.1.3  Function 1

The parameters for Function 1 of the GPIO controller _DSM method are defined as follows:

Arguments:

Arg0: UUID for GPIO controller _DSM

GUID: // {4F248F40-D5E2-499F-834C-27758EA1CD3F}

DEFINE_GUID (GPIO_CONTROLLER _DSM_GUID,

0x4f248f40, 0xd5e2, 0x499f, 0x83, 0x4c, 0x27, 0x75, 0x8e, 0xa1, 0xcd. 0x3f);

Arg1: Revision ID

#define GPIO_CONTROLLER _DSM_REVISION_ID     0

Arg2:  Function index for ActiveBoth asserted polarity:

#define GPIO_CONTROLLER_DSM_ACTIVE_BOTH_POLARITY_FUNCTION_INDEX  1

Arg3: Package empty (not used)

Return:

A Package of integers, each of which is the controller-relative pin number of a pin on the GPIO controller that is:

·         Defined to be an ActiveBoth interrupt, and

·         Whose asserted state is not logic low (in other words, is logic high).

A.1.4  Example

//

// _DSM - Device-Specific Method

//

// Arg0:    UUID       Unique function identifier

// Arg1:    Integer    Revision Level

// Arg2:    Integer    Function Index (0 = Return Supported Functions)

// Arg3:    Package    Parameters

//

Function(_DSM,{BuffObj, PkgObj, IntObj},{BuffObj, IntObj, IntObj, PkgObj})

{

    //

    // Switch based on which unique function identifier was passed in

    //

    //

    // GPIO CLX UUID

    //

    If(LEqual(Arg0,ToUUID("4F248F40-D5E2-499F-834C-27758EA1CD3F")))

    {

        switch(Arg2)

        {

            //

            // Function 0: Return supported functions, based on

            //    revision

            //

            case(0)

            {

                // Revision 0+: Functions 0 & 1 are supported

                return (Buffer() {0x3})

            }

            //

            // Function 1: For emulated ActiveBoth controllers,

            //    returns a package of controller-relative pin

            //    numbers. Each corresponding pin will have an

            //    initial polarity of ActiveHigh.

            //

            //    A pin number of 0xffff is ignored.

            //

            case(1)

            {    

                // Marks pins 0x28, 0x29 and 0x44 to be ActiveHigh.

                Return (Package() {0x28, 0x29, 0x44})

            }

            //

            // Unrecognized function for this revision

            //

            default

            {

                BreakPoint

            }

        }

    }

    else

    {

        //

        // If this is not one of the UUIDs we recognize, then return

        // a buffer with bit 0 set to 0 to indicate that no functions

        // are supported for this UUID.

        //

        return (Buffer() {0})

    }

}

A.2  Battery Device-Specific Method

To support the passive thermal management of the battery by the platform, Microsoft defines a _DSM method to communicate to the platform firmware the thermal throttling limit set by the battery's thermal zone. For more information, see the discussion of "Thermal Zones" in section 2.7.4 of this paper.

A.2.1  Function 1: Battery Thermal Limit

The _DSM control method parameters for the battery charging thermal limit function are as follows:

Arguments:

Arg0: UUID = 4c2067e3-887d-475c-9720-4af1d3ed602e

Arg1: Revision = 0

Arg2: Function index = 1

Arg3: Thermal limit (integer value from 0 to 100)

Return:

None. Firmware is responsible for taking the current thermal limit into account when engaging charging.

A.3  Device-Specific Method for Microsoft Thermal Extensions

To support more flexible design of thermal zones  and thermal sensors, Windows supports extensions to the ACPI thermal zone model. Specifically, Windows supports a thermal minimum throttle limit (MTL) for each thermal zone, and also supports sharing a temperature sensor between thermal zones. For more information about MTL, see the document titled "Thermal Management in Windows" on the Microsoft Connect website at .

To use these features, OEMs can include the following Device-Specific Method (_DSM) in the namespace of any thermal zone.

A.3.1  Function 1: Minimum Throttle Limit

The _DSM control method parameters for the thermal minimum throttle limit are as follows:

Arguments:

Arg0: UUID = 14d399cd-7a27-4b18-8fb4-7cb7b9f4e500

Arg1: Revision ID = 0

Arg2: Function index = 1

Arg3: Empty package (not used)

Return:

An integer value with the current minimum throttle limit, expressed as a percentage. Windows will not set the throttle limit below this value.

A.3.2  Function 2: Temperature Sensor Device

The _DSM control method parameters for the temperature sensor device are as follows:

Arguments:

Arg0: UUID = 14d399cd-7a27-4b18-8fb4-7cb7b9f4e500

Arg1: Revision ID = 0

Arg2: Function index = 2

Arg3: Empty package (not used)

Return:

A reference to the device that will return the temperature of this thermal zone.

A.3.3  Temperature Sensor Device Dependency Requirement

If a temperature sensor device is reported via _DSM function index 2, the thermal zone is additionally required to include a _DEP object that identifies the thermal zone's dependence on the temperature sensor device.

Note  Function index 0 of every _DSM is a query function that returns the set of supported function indexes, and is always required. For more information, see section 9.14.1, "_DSM (Device Specific Method)", of the ACPI 5.0 specification.

A.4  USB Device-Specific Method (_DSM)

To support device-class-specific configuration of the USB subsystem, Windows defines a Device-Specific Method (_DSM) with the following functions.

A.4.1  Function 1: Post-Reset Processing for Dual-Role Controllers

The _DSM control method parameters for the post-reset processing function for dual-role USB controllers are as follows:

Arguments:

Arg0: UUID = ce2ee385-00e6-48cb-9f05-2edb927c4899

Arg1: Revision ID = 0

Arg2: Function index = 1

Arg3: Empty package (not used)

Return:

None.

The Windows inbox drivers only support USB controllers in host mode. After each controller reset, the USB driver will invoke the _DSM function index 1 to perform any controller-specific initialization required to configure the USB controller to operate in host mode.

When this function is used, the _DSM method must appear under the USB controller device.

A.4.2  Function 2: Port Type Identification

The _DSM control method parameters for identifying the USB port type are as follows:

Arguments:

Arg0: UUID = ce2ee385-00e6-48cb-9f05-2edb927c4899

Arg1: Revision ID = 0

Arg2: Function index = 2

Arg3: Empty package (not used)

Return:

An integer containing one of the following values:

Element	Object type	Description
Port type	Integer (BYTE)	Specifies the type of the USB port:     0x00:                  Regular USB     0x01:                  HSIC     0x02                   SSIC     0x03 – 0xff        Reserved

When this function is used, the _DSM method must appear under the USB port device.

Note  Function index 0 of every _DSM is a query function that returns the set of supported function indexes, and is always required. For more information, see section 9.14.1, "_DSM (Device Specific Method)", of the ACPI 5.0 specification.

A.5  HIDI2C Device-Specific Method (_DSM)

The _DSM method is defined in section 9.14.1 of the ACPI 5.0 specification. This method provides for individual, device-specific data and control functions that can be called by a device driver without conflicting with other such device-specific methods. The _DSM for a particular device or class defines a UUID (GUID) that is guaranteed not to clash with other UUIDs. For each UUID, there is a set of defined functions that the _DSM method can implement to provide data or perform control functions for the driver.

For the HIDI2C class of devices, Function 1 is defined as follows:

Arguments:

Arg0: UUID = 3cdff6f7-4267-4555-ad05-b30a3d8938de

Arg1: Revision ID = 1

Arg2: Function index = 1

Arg3: None

Return:

An integer containing the HidDescriptorAddress. This address is the register offset in the I2C device at which the HID descriptor(s) can be read.

Note   Function index 0 of every _DSM is a query function that returns the set of supported function indexes, and is always required. For more information, see section 9.14.1, "_DSM (Device Specific Method)", of the ACPI 5.0 specification.

A.6  Windows Button Array Device-Specific Method (_DSM)

To support evolution of the Windows Button UI, Windows defines a Device-Specific Method (_DSM) for the Windows Button Array device with the following functions.

A.6.1  Function 1: Power Button Properties

The _DSM control method parameters for the power button properties function are as follows:

Arguments:

Arg0: UUID = dfbcf3c5-e7a5-44e6-9c1f-29c76f6e059c

Arg1: Revision ID = 0

Arg2: Function index = 1

Arg3: Empty package (not used)

Return:

An integer (DWORD) with the following bit-field definitions:

?        Bits 31 to 33: Reserved (must be 0).

?        Bit 2: This bit should be set to 1 if the power button is configured to detect both press and release events, and to report these events to the operating system. Otherwise, this bit should be 0.

?        Bit 1: This bit should be set to 1 if power button is wired to an interrupt controller (GPIO or otherwise) that supports level-detection. Otherwise, this bit should be 0.

?        Bit 0: This bit should be set to 1 if the platform supports ACPI Power Button Override time of 10 seconds or greater. Otherwise, this bit should be 0.

Note  Function index 0 of every _DSM is a query function that returns the set of supported function indexes, and is always required. For more information, see section 9.14.1, "_DSM (Device Specific Method)", of the ACPI 5.0 specification.

Appendix B: GPIO Controller Requirements Checklist

This appendix summarizes the hardware, firmware, and software requirements for GPIO controller devices that are exposed to Windows.

B.1  Hardware

?        The GPIO controller is integrated into the SoC (not connected by an SPB bus).

o   Increases reliability of Emulated ActiveBoth.

?        Level-mode interrupts are supported.

o   Required for both Emulated ActiveBoth and Debounce Emulation features.

?        Both High and Low interrupt polarities are supported.

o   Required for both Emulated ActiveBoth and Debounce Emulation features.

?        Interrupt polarity can be re-programmed at run time.

o   Required for both Emulated ActiveBoth and Debounce Emulation features.

B.2  Firmware

?        GPIO controller _CRS includes all resources for all pin banks in the controller.

?        GPIO controller _CRS  resource ordering provides bank-to-system interrupt mapping.

?        _AEI method, and event method(s) (_Exx, _Lxx or _EVT) exist for any GPIO-signaled ACPI events.

?        GPIO controller _DSM included if any ActiveBoth interrupts connected to the controller are asserted logic high instead of logic low.

?        Implement _REG methods for each GPIO controller and prevent use of GeneralPurposeIO OpRegions if _REG indicates that the region handler is not available.

?        Debounce timeout is included in the GPIOInt resource descriptor for any interrupt that requires debouncing.

B.3  Driver

?        Support version 2 of the interface between GpioClx and the GPIO controller driver:

o   Implement the callback function.

§  Greatly assists in diagnosing interrupt storms.

o   If the BankIdlePowerMgmtSupported flag is set in the structure, the GPIO controller driver must implement the and callback functions, and these functions must save/restore bank context appropriately, including the masked/unmasked state of the interrupts. Note that interrupts are not guaranteed to be disconnected at the time this function is called, but, if they are still connected, they are guaranteed to be masked.

o   If the DeviceIdlePowerMgmtSupported flag is set in the structure, the and callback functions must save/restore context for all banks appropriately, including the masked/unmasked state of the interrupts. Note that interrupts are not guaranteed to be disconnected at the time this function is called, but, if they are still connected, they are guaranteed to be masked.

?        Set the EmulateDebouncing flag in the structure.

o   Significantly increases noise immunity for devices whose  interrupts are subject to electrostatic discharge (such as buttons, plugs, and so on).

?        Set the EmulateActiveBoth flag in the structure, and implement the callback function.

o   Ensures reliable edge detection for ActiveBoth interrupts.

References and Resources

?        The Advanced Configuration and Power Interface Specification, Revision 5.0, is available on the ACPI website at .

?        For all firmware requirements, see the documentation for the Windows Certification Program at .

?        The Core System Resources Table (CSRT) specification is available at http://acpica.org/related-documents.

?        The Microsoft Debug Port Table 2 (DBG2) specification is available at .

?        For more information about the AMLI debugger and other ACPI debugging extensions, see the "ACPI Debugging" topic at .

?        For more information about configuring USB ports, see the "Using ACPI to Configure USB Ports on a Computer" topic at .

?        For more information about reporting camera location, see the "Windows 8 Requirement: Identifying the Location of Internal Cameras" white paper at .

?        For more information about battery management in Windows, see the "Windows Power and Battery Subsystem Requirements at .

?        For more information about the Windows button driver, see the "Hardware Buttons for Windows 8 Tablet and Convertible Devices" white paper at .