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

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

Windows ACPI Design Guide for SoC Platforms

September 10, 2013

Abstract

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

Thisinformation applies to the following operating systems:
        Windows 8.1

        Windows 8

       

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

The current version of thispaper is maintained on the Web at:
        http://msdn.microsoft.com/library/windows/hardware/gg463220

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

Some examplesdepicted herein are provided for illustration only and are fictitious. Noreal association or connection is intended or should be inferred.

This document does notprovide you with any legal rights to any intellectual property in any Microsoftproduct. You may copy and use this document for your internal, referencepurposes. 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. PAGEREF_Toc366660278 \h 3

1.1  Scope. PAGEREF_Toc366660279 \h 3

1.2  Firmware RevisionSupport. PAGEREF_Toc366660280 \h 4

2        ACPISupport in Windows. PAGEREF_Toc366660281 \h 4

2.1  ACPI Hardware Features. PAGEREF_Toc366660282 \h 5

2.1.1  ACPI HardwareSpecification. PAGEREF_Toc366660283 \h 5

2.1.2  ACPI Events. PAGEREF_Toc366660284 \h 6

2.2  System DescriptionTables. PAGEREF_Toc366660285 \h 6

2.2.1  Root SystemDescription Pointer (RSDP). PAGEREF_Toc366660286 \h 7

2.2.2  Root SystemDescription Table (RSDT). PAGEREF _Toc366660287 \h 7

2.2.3  Fixed ACPIDescription Table (FADT). PAGEREF _Toc366660288 \h 7

2.2.4  Multiple APICDescription Table (MADT). PAGEREF _Toc366660289 \h 8

2.2.5  Generic TimerDescription Table (GTDT). PAGEREF _Toc366660290 \h 8

2.2.6  Core SystemResources Table (CSRT). PAGEREF_Toc366660291 \h 8

2.2.7  Debug Port Table 2(DBG2). PAGEREF_Toc366660292 \h 9

2.2.8  DifferentiatedSystem Description Table (DSDT). PAGEREF_Toc366660293 \h 10

2.3  Device ManagementNamespace Objects. PAGEREF_Toc366660294 \h 11

2.3.1  DeviceIdentification in Windows. PAGEREF _Toc366660295 \h 11

2.3.2  DeviceIdentification in ACPI PAGEREF_Toc366660296 \h 12

2.3.3  Device ConfigurationObjects. PAGEREF_Toc366660297 \h 14

2.3.4  Device StatusChanges. PAGEREF_Toc366660298 \h 14

2.3.5  Enable/Disable. PAGEREF_Toc366660299 \h 14

2.3.6  Device Dependencies. PAGEREF_Toc366660300 \h 15

2.4  General-Purpose I/O(GPIO). PAGEREF_Toc366660301 \h 16

2.4.1  GPIO ControllerDevices. PAGEREF _Toc366660302\h 16

2.4.2  GPIO NamespaceObjects. PAGEREF_Toc366660303 \h 17

2.5  Simple Peripheral Bus(SPB). PAGEREF_Toc366660304 \h 20

2.5.1  SPB ControllerDevices. PAGEREF_Toc366660305 \h 20

2.6  Device PowerManagement. PAGEREF_Toc366660306 \h 20

2.6.1  Device PowerManagement in Windows. PAGEREF_Toc366660307 \h 20

2.6.2  Device PowerManagement in ACPI PAGEREF_Toc366660308 \h 21

2.7  ACPI-Defined Devices. PAGEREF_Toc366660309 \h 23

2.7.1  Lid Device. PAGEREF_Toc366660310 \h 24

2.7.2  Control Method BatteryDevice. PAGEREF_Toc366660311 \h 24

2.7.3  Control Method Timeand Alarm Device. PAGEREF_Toc366660312 \h 24

2.7.4  Thermal Zones. PAGEREF_Toc366660313 \h 25

2.8  Other NamespaceObjects. PAGEREF_Toc366660314 \h 26

2.8.1  ProcessorIdentification Objects. PAGEREF_Toc366660315 \h 26

2.8.2  Display-SpecificObjects. PAGEREF_Toc366660316 \h 26

2.8.3  USB Host Controllersand Devices. PAGEREF_Toc366660317 \h 27

2.8.4 SD Host Controllers andDevices. PAGEREF_Toc366660318 \h 28

2.8.5  Imaging ClassDevices (Cameras). PAGEREF_Toc366660319 \h 30

2.8.6  HID-over-I2C Devices. PAGEREF_Toc366660320 \h 32

2.8.7  Button Devices. PAGEREF_Toc366660321 \h 33

2.8.8  Dock and ConvertiblePC Sensing Devices. PAGEREF_Toc366660322 \h 34

Appendix A: Device-Specific Methods. PAGEREF_Toc366660323 \h 35

A.1  GPIO ControllerDevice-Specific Method (_DSM). PAGEREF_Toc366660324 \h 35

A.1.1  Definition. PAGEREF_Toc366660325 \h 35

A.1.2  Function 0. PAGEREF_Toc366660326 \h 36

A.1.3  Function 1. PAGEREF_Toc366660327 \h 36

A.1.4  Example. PAGEREF_Toc366660328 \h 36

A.2  BatteryDevice-Specific Method. PAGEREF_Toc366660329 \h 38

A.2.1  Function 1: BatteryThermal Limit. PAGEREF_Toc366660330 \h 38

A.3  Device-Specific Methodfor Microsoft Thermal Extensions. PAGEREF _Toc366660331\h 38

A.3.1  Function 1: MinimumThrottle Limit. PAGEREF_Toc366660332 \h 38

A.3.2  Function 2:Temperature Sensor Device. PAGEREF _Toc366660333 \h 39

A.3.3  Temperature SensorDevice Dependency Requirement. PAGEREF_Toc366660334 \h 39

A.4  USB Device-SpecificMethod (_DSM). PAGEREF_Toc366660335 \h 39

A.4.1  Function 1:Post-Reset Processing for Dual-Role Controllers. PAGEREF_Toc366660336 \h 39

A.4.2  Function 2: PortType Identification. PAGEREF_Toc366660337 \h 40

A.5  HIDI2C Device-SpecificMethod (_DSM). PAGEREF_Toc366660338 \h 40

A.6  Windows Button ArrayDevice-Specific Method (_DSM). PAGEREF_Toc366660339 \h 41

A.6.1  Function 1: PowerButton Properties. PAGEREF_Toc366660340 \h 41

Appendix B: GPIO ControllerRequirements Checklist. PAGEREF_Toc366660341 \h 42

B.1  Hardware. PAGEREF_Toc366660342 \h 42

B.2  Firmware. PAGEREF_Toc366660343 \h 42

B.3  Driver. PAGEREF_Toc366660344 \h 42

References and Resources. PAGEREF_Toc366660345 \h 43

1       Purpose

This paper describes Advanced Configuration and PowerInterface (ACPI) support in Windows for hardware platforms that use System on aChip (SoC) integrated circuits. This support is based on the ACPI 5.0specification, found at http://www.acpi.info.ACPI 5 has many enhancements to enable support of non-PC architectures, which includeSoC-based mobile platforms, but carries forward many useful features alreadysupported by Windows. The purpose of this paper is to direct implementers tothe parts of ACPI 5 that specifically apply to SoC platforms, and to describebest practices for implementing the SoC-specific features in ACPI to runWindows on these platforms.

1.1  Scope

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

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

1.2  Firmware Revision Support

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

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

2       ACPISupport in Windows

The subset of ACPI 5 features required to support Windowson SoC platforms is summarized in the following table, and is covered in moredetail 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 here)	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 platformsto implement any of the features described in chapter 4, "ACPI HardwareSpecification", of the ACPI 5.0 specification. ACPI fixed hardware featuressuch 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 Hardwareinterface are referred to as hardware-reduced ACPI platforms. To indicate that a platform is hardware-reduced, set the HW_REDUCED_ACPIflag in the Fixed ACPI Description Table (FADT).

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

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

Windows supports platforms that have low-power S0-idlecapability regardless of whether they implement hardware-reduced ACPI or fullACPI. However, as required by the ACPI 5.0 specification, Windows does not usetraditional 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 forsignaling hardware events. Windows supports many events defined in thespecification, and this support carries over to SoC platforms. However, for hardware-reducedACPI platforms, GPIO interrupts are used to signal the events, instead of theACPI-defined GPE/SCI hardware. After an event is signaled, however, event handlingis identical between hardware-reduced and full ACPI platforms. In both cases,the ACPI-specified event-handling mechanism invokes the appropriate controlmethod (handler) for the event, which ultimately sends an ACPI-definednotification to the appropriate device driver.

For more information about GPIO-signaled ACPI events, see section5.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 notrequired on SoC platforms, but much of the ACPI Software Specification is (orcan be) required. ACPI defines a generic, extensible table-passing mechanism, plusspecific tables for describing the platform to the operating system. Tablestructures and headers, including ID and checksum fields, are defined in the ACPI5.0 specification. Windows utilizes this table mechanism, as well as thespecific tables described in the following paragraphs.

Note  The idea behind these tables is to enable generic software to support standard intellectualproperty (IP) blocks that can be integrated into various platforms in diverseways. With the table strategy, the platform-variable attributes of a particularplatform are provided in a table, and used by generic software to adapt itselfto the specific set of IP blocks integrated into the platform. This softwarecan 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 describedin section 5.2.5.2, "Finding the RSDP on UEFI Enabled Systems", ofthe ACPI 5.0 specification. The platform firmware fills in the address ofeither 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 systemdescription tables provided on the platform. Specifically, this table containspointers 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 importantinformation about the various Fixed Hardware features available on the platform.To support hardware-reduced ACPI platforms, ACPI 5 extends the FADT tabledefinition as follows:

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

o  HARDWARE_REDUCED_ACPI – Bit offset 20. Indicatesthat ACPI hardware is not available on this platform. This flag must be set ifthe 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 systempower state that are more energy efficient than any Sx sleep state. If this flag is set, Windows will not try to sleepand resume, but will instead use platform idle states and Connected Standby.

?       The FADT Preferred_PM_Profile field (byte offset45) has a new role entry, "Tablet". This role influences powermanagement policy for the display and input, and affects the display ofon-screen keyboards.

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

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

?       If the HARDWARE_REDUCED_ACPI flag is set, allfields relating to the ACPI Hardware Specification are ignored by the operatingsystem.

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

2.2.4  Multiple APIC Description Table (MADT)

In PC implementations of ACPI, the Multiple APICDescription Table (MADT) and PC-specific interrupt controller descriptors areused to describe the system interrupt model. For ARM-based SoC platforms, ACPI5 adds descriptors for the ARM Holdings' Generic Interrupt Controller (GIC) andGIC Distributor. Windows includes inbox support for the GIC and GICDistributor. For more information about these descriptors, see sections5.2.12.14, "GIC Structure", and 5.2.12.15, "GIC DistributorStructure", of the ACPI 5.0 specification.

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

2.2.5  Generic Timer Description Table (GTDT)

As with the interrupt controller, there is a standardtimer 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 inWindows.

2.2.6  Core System Resources Table (CSRT)

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

Windows supports the concept of HAL extensions to address this issue. HAL extensions areSoC-specific modules, implemented as DLLs, that adapt the Windows HAL to aspecific hardware interface of a specific class of CSR required by Windows. Inorder to identify and load these non-standard CSR modules, Microsoft hasdefined 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 CSRsare used on the platform.

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

To support maintenance of HAL extensions, and to managethe system resources used by these extensions, each resource group described inthe 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 theidentifiers used in the device's namespace node (see section 2.3.2, "DeviceIdentification in ACPI", below). The existence of these resource group namespacedevices 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. Todescribe the debug port(s) built into a platform, Microsoft defines the DebugPort Table 2 (DBG2) for ACPI. This table specifies one or more independentport(s) for debugging purposes. The presence of the DBG2 table indicates thatthe platform includes at least one debug port. This table includes informationabout the identity and configuration of the debug port(s). The table is locatedin system memory with other ACPI tables, and must be referenced in the ACPIRSDT table.

Windows uses the Port Type value in the DBG2 table toidentify and load the Kernel Debugger (KD) transport (for example, USB orserial) that the system requires. The KD transport then uses the Port Subtypevalue 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 ACPInamespace that corresponds to the debug port. This reference enables Windows tomanage 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 http://msdn.microsoft.com/hh673515.

2.2.8  Differentiated System Description Table (DSDT)

In ACPI, peripheral devices and system hardware featureson 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, theplatform configuration is typically static, so the DSDT might be sufficient,although SSDTs can also be used to improve the modularity of the platformdescription.

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

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

Windows provides support for developing and debugging ASLcode. The ASL compiler  includes adisassembler 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 forrapid prototyping and testing—without having to flash the system firmware. Inaddition, the Windows Kernel Debugger, in conjunction with a checked (CHK)version of the Windows-provided Acpi.sys driver, supports tracing and analyzingAML execution. For more information, see the "ACPI Debugging" topicat http://msdn.microsoft.com/library/ff537808(v=VS.85).aspx.

2.2.8.1  ACPI Namespace

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

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

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

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

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

?       Any "private" buses or devices (forexample, I2S) that are dedicated to the use of one function driver (forexample, 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 inthe function device's resource list in the namespace. For more information, seesection 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 andmethods are used for common operating system functions such as platformdescription (for example, device identification and system resourceallocations), generic device control (for example, configuring resources andcontrolling power resources), or class-specific feature control (for example,dimming displays or reporting battery status). The sections that follow listthe set of namespace objects used on SoC platforms, and include implementationguidance 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 basedon a device identifier provided by the enumerator of the device. Enumeratorsare bus drivers that know how to extract identification information from thedevice. Some buses (such as PCI, SD, and USB) have hardware-defined mechanismsto do this extraction. For buses that do not (such as the processor bus or a simpleperipheral bus), ACPI defines identification objects in the namespace.

The ACPI driver assembles the values found in theseobjects into a variety of device identifier strings that can identify a devicevery 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 createsfor your device by opening DeviceManager and inspecting the HardwareIDs and Compatible IDs propertiesof the enumerated device. Each of these strings is available to be specified inan INF file to identify the driver to load for the device. The order of INFmatching is from the most specific hardware identifier (most preferred driver)to the least specific identifier (least preferred driver), so that drivers thatknow more about the specific features of the device can replace those that areless specific (and therefore support only a subset of the device features).

Device identifiers should be used only for INFmatching, and should never be parsed or processed by the device driver. If thedevice 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 atinstall time. The driver can then access these keys during initialization toobtain 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 ACPIis the Hardware ID (_HID) object. _HID returns a string with the format of "ABC[D]xxxx", where "ABC[D]" isa 3- or 4-character string that identifies the manufacturer of the device (the"Vendor ID"), and xxxx is ahexadecimal number that identifies the specific device manufactured by thatvendor (the "Device ID"). Vendor IDs must be unique across the industry.Microsoft allocates these strings to ensure that they are unique. Vendor IDscan be obtained from the Microsoft PNPID website at http://msdn.microsoft.com/windows/hardware/gg463195.aspx.

Note  ACPI5 also supports the use of PCI-assigned vendor IDs in _HID and otheridentification objects, so you might not need to get a vendor ID fromMicrosoft. For more information about hardware identification requirements, seesection 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" fordevices that are compatible with inbox drivers shipped with Windows. Windowsdefines a number of device IDs for use with this vendor ID that can be used toload the Windows-provided driver for a device. A separate object, the CompatibleID (_CID) object, is used to return these identifiers. Windows always prefers HardwareIDs (returned by _HID) over Compatible IDs (returned by _CID) in INF matchingand driver selection. This preference allows the Windows-provided driver to betreated as a default driver if a vendor-provided device-specific driver is notavailable. The Compatible IDs in the following table are newly created for usewith 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 canbe used along with the _HID to create identifiers that more uniquely identify aspecific version, integration, or hardware revision of a device, or to indicatemembership in a PCI-defined device class. These objects are generally optional,but might be required by certain device classes in Windows. For moreinformation about these objects, see section 6.1, "Device IdentificationObjects", of the ACPI 5.0 specification.

For serviceability, there is a WHCK requirement thatdevice IDs on OEM systems be "four-part" IDs. The four parts are the vendorID, the device ID, the subsystem vendor (OEM) ID, and the subsystem (OEM) deviceID. 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 methodprovides for individual, device-specific data and control functions that can becalled by a device driver without conflicting with other such device-specificmethods. 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 setof defined functions that the _DSM method can implement to provide data or to performcontrol functions for the driver. Class-specific data and data formats areprovided in separate device-class-specific specifications, and are also discussedlater 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 deviceidentification:

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

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

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

2.3.3  Device Configuration Objects

For each device identified in the namespace, the systemresources (memory addresses, interrupts, and so on) consumed by the device mustalso be reported by the Current Resource Settings (_CRS) object. Note thatreporting of multiple possible resource configurations (_PRS) and controls forchanging 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 moreinformation. Also new for SoC platforms is a general-purpose fixed DMAdescriptor. The FixedDMA descriptor supports the sharing of DMA controller hardwareby a number of system devices. The DMA resources (request line and channelregisters) statically allocated to a particular system device are listed in theFixedDMA 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 avariety of reasons. The Status (_STA) object is provided to enable such statuschanges to be communicated to the operating system. For a description of _STA, seesection 6.3.7 of the ACPI 5.0 specification. Windows uses _STA  to determine if the device should beenumerated, shown as disabled, or not visible to the user. This control in the firmwareis useful for many applications, including docking and USB OTG host-to-functionswitching.

Additionally, ACPI provides a notification mechanism thatASL can use to notify drivers of events in the platform, such as a device beingremoved 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, "DeviceObject Notifications", of the ACPI 5.0 specification,

2.3.5  Enable/Disable

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

On-SoC devices are integrated into the SoC chip and cannotbe removed. Drivers for most on-SoC devices can be exempted from therequirements for enable and disable. For more information, see the documenttitled "Reducing PNP Requirements for SoC Drivers" on the MicrosoftConnect website at http://connect.microsoft.com/site1304/Downloads/DownloadDetails.aspx?DownloadID=47560.For those drivers that are not exempt, there are driver interfaces forindicating that the driver supports orderly removal. For more information aboutthese interfaces, see the above document and MSDN.

If a driver supports orderly removal, and the devicehardware can be disabled (that is, the device can be configured to stopaccessing its assigned resources), then the ACPI namespace node for the devicecan include the Disable (_DIS ) object. This method will be evaluated by the operatingsystem whenever the driver is removed. Use of _DIS has the following additionalrequirements:

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

·        The device must provide the Set ResourceSettings (_SRS) object to re-enable the device hardware and set the above bitin _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 deviceson a particular platform. Windows requires all such dependencies be describedso that it can ensure that all devices function correctly as things changedynamically in the system (device power is removed, drivers are stopped andstarted, and so on). In ACPI, dependencies between devices are described in thefollowing ways:

1.       NamespaceHierarchy. Any device that is a child device (listed as a device within thenamespace of another device) is dependent on the parent device. For example, aUSB 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 systemMMU device is dependent on the MMU device.

2.       ResourceConnections. Devices connected to GPIO or SPB controllers are dependent onthose controllers. This type of dependency is described by the inclusion ofConnection Resources in the device's _CRS.

3.       OpRegionDependencies. For ASL control methods that use OpRegions to perform I/O,dependencies are not implicitly known by the operating system because they areonly determined during control method evaluation. This issue is particularly applicableto GeneralPurposeIO and GenericSerialBus OpRegions in which Plug and Playdrivers provide access to the region. To mitigate this issue, ACPI defines theOperation Region Dependency (_DEP) object. _DEP should be used in any devicenamespace in which an OpRegion (HW resource) is referenced by a control method,and neither 1 nor 2 above already applies for the referenced OpRegion'sconnection 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 devicedrivers. These dependencies must also be described. For more information, seethe following resources:

?       For driver-load-order dependencies, see the "HowTo Control Device Driver Load Order" article at http://support.microsoft.com/kb/115486.

?       For power-relations dependencies, see:

o  The IoInvalidateDeviceRelations reference page at http://msdn.microsoft.com/library/ff549353(VS.85).aspx (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 http://msdn.microsoft.com/library/ff551670(v=VS.85).aspx

o  The "Enumerating the Devices on a Bus"topic at  http://msdn.microsoft.com/library/ff540819(v=VS.85).aspx

o  The "Dynamic Enumeration" topic at http://msdn.microsoft.com/library/ff540812(v=VS.85).aspx

o  The WdfDeviceInitSetPnpPowerEventCallbacks reference page at  http://msdn.microsoft.com/library/ff546135(v=VS.85).aspx

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, andthis abstraction requires support from the ACPI namespace. The GPIO abstractionis supported by the ACPI 5.0 definitions listed in the following sections.

2.4.1  GPIO Controller Devices

Windows supports GPIO controllers. GPIO controllersprovide a variety of functions for peripheral devices, including interrupts,input signaling, and output signaling. GPIO capabilities are modeled as a GPIO controllerdevice in the namespace. The GPIOframework extension (GpioClx) models the GPIO controller device as beingpartitioned into some number of banks of pins. Each pin bank has 64 or fewerconfigurable pins. The banks in a GPIO controller are ordered relative to theirpins' position within the controller-relative GPIO pin space. For example, bank0 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 mighthave fewer. Banks are significant for the ACPI firmware because the firmwaremust report the mapping of system interrupt resources to banks, as described insection 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 describehow the pin is to be configured.

2.4.1.1  GPIO Controllers and ActiveBoth Interrupts

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

Logically, ActiveBoth signals have both an Asserted andUnasserted state, whether they are momentary assertions (for example,pushbuttons), or indefinitely long assertions (for example, headphone jackinsertions). Edge detection for ActiveBoth interrupts might be implemented inthe GPIO controller hardware (Hardware ActiveBoth), or be emulated in the GPIO driversoftware (Emulated ActiveBoth). Windows requires that GPIO controllers thatimplement ActiveBoth must use Emulated ActiveBoth. This is required to ensurerobust handling of double-edged interrupts for all scenarios. In support ofActiveBothEmulation, the following hardware requirements apply:

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

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

3.      To establish a deterministic initial state forActiveBoth interrupt signals, the Windows GPIO device stack guarantees that thefirst interrupt generated after connection of the interrupt by the driver willalways be for the signal's asserted state. The stack further assumes that theasserted state of all ActiveBoth interrupt lines is logic level low (theActiveLow edge) by default. If this is not the case on your platform, you canoverride 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 thatuses ActiveBoth might receive an interrupt immediately after initializing(connecting to) the interrupt, if the signal at the GPIO pin is in the assertedstate at that time. This is possible, and even likely for some devices (forexample, headphones), and must be supported in the driver.

To support emulated ActiveBoth, the GPIO controller drivermust enable ("opt-in to") ActiveBoth emulation by implementing a CLIENT_ReconfigureInterrupt callbackfunction, and by setting the EmulateActiveBoth flag  in the basic information structurethat the driver's CLIENT_QueryControllerBasicInformation callback function supplies to GpioClx. For more information, see the GPIO driverdocumentation on MSDN at http://msdn.microsoft.com/library/hh439508(v=vs.85).aspx.

2.4.2  GPIO Namespace Objects

GPIO controllers, and the peripherals that connect tothem, are enumerated by ACPI. The connection between them is described usingGPIO Connection Resource Descriptors. For more information, see section6.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 thanone instance of the GPIO controller in the namespace (i.e., two or morenamespace 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 ofthe banks in the GPIO controller. The interrupt resource-to-bank mapping isrepresented 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 onelisted is assigned to bank 1, and so on. Banks can share interrupt resources, inwhich case the interrupt is listed once for each bank connected to it, in bankorder, and is configured as Shared.

2.4.2.2  GPIO Connection Resource Descriptors

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

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

2.4.2.3  GPIO-Signaled ACPI Events

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

For SoC platforms, GPIO interrupts are used to signalplatform 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 towhich the ACPI event signal is connected must include a GpioInt resource forthat 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 _AEIobject.

The ACPI driver handles the listed GPIO interrupt andevaluates the Edge, Level or Event control method for it. The control methodquiesces the hardware event, if necessary, and executes the required Notifyoperator on the event source device's namespace node. Windows then sends thenotification to the device's driver. Multiple events can be signaled over thesame GpioInt resource if the event control method can query the hardware todetermine which event occurred. The method must then notify the correct devicewith the correct notification code.

2.4.2.3.1  ACPI Event Information (_AEI) Object

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

2.4.2.4  GeneralPurposeIO Operation Regions (OpRegions)

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

GeneralPurposeIO Operation regions (see section 5.5.2.4.4of the ACPI 5.0 specification) are declared within the namespace scope of theGPIO controller device whose driver will handle the I/O. GeneralPurposeIO Fielddeclarations (see section 5.5.2.4.4.1 of the ACPI 5.0 specification) assignnames 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) andconfiguration for a particular Field reference. The total number of named fieldbits following a connection descriptor must equal the number of pins listed inthe descriptor.

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

Note  BecauseOpRegion access is provided by the GPIO controller device driver (the "OpRegionHandler"), methods must take care not to access an OpRegion until thedriver is available. ASL code can track the state of the OpRegion handler byincluding a Region (_REG) method under the GPIO controller device (see section6.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 usedunder 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/Oresources that are also assigned to GeneralPurposeIO OpRegions. Opregions arefor the exclusive use of ASL control methods.

To verify that your GPIO controller meets all Windowsplatform requirements, see Appendix B, "GPIO Controller RequirementsChecklist", later in this paper.

2.5  Simple Peripheral Bus (SPB)

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

2.5.1  SPB Controller Devices

A SPB controller device is identified in the namespacewith 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 tothe operating system by the consuming device, via new resource descriptors. TheGeneric Serial Bus Resource Descriptor is used to declare I2C connections, SPIconnections, and UART connections, and is extensible to support other serialbus types in the future.

Resource Template Macros for these descriptors aredescribed in section 19.5.55, "I2CSerialBus (I2C Serial Bus ConnectionResource 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 Regionfor use with SPB controllers, GenericSerialBus (section 5.5.2.4.5 of the ACPI5.0 specification). Because SPBs are communication buses,  GenericSerialBus OpRegions support variousprotocols for accessing SPB target devices. For more information, see section5.5.2.4.5.3, "Using the GenericSerialBus Protocols", of the ACPI 5.0specification.

Often with SPBs, it is necessary for ASL control methodsto share access to a SPB target device with the operating system driver forthat device. To ensure synchronization of these accesses, ACPI 5 defines theDevice Lock Mutex (_DLM) object. For more information, see section 5.7.5 of theACPI 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 theACPI-defined working state, S0), individual devices can make transitionsbetween device power states, depending on activity, to save power. Intraditional PC systems, ACPI-defined sleeping states (S1 through S4) are alsoused to save power, but these disconnected, high-latency sleep states are notused on Windows SoC platforms. Therefore, battery life is highly dependent onhow platforms implement run-time device power management.

Devices integrated into the SoC can be power-managedthrough the Windows Power Framework (PoFx). These framework-integrated devicesare 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. Formore information about PoFx, see Overviewof the Power Management Framework on MSDN.

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

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 supportsthe D3cold power management capabilities defined in the ACPI 5.0 specification.With this support, devices, platforms and drivers can opt-in to having devicepower completely removed during run-time idle periods. This capability cansignificantly improve battery life. However, removing power must be supportedby 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 driveropt-in, see SupportingD3cold in a Driver 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 statesconsuming less power than lower-numbered states. Further, the D3 (off) statehas two sub-states, D3hot and D3cold. The D3hot sub-state requires the deviceto remain accessible on its parent bus so that it can respond to bus-specific softwarecommands. 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 ahardware event, and, if necessary, to also bring the platform out of an idlestate.

The platform indicates its support for D3cold by grantingthe OS control of the "_PR3 Support" feature (bit 2) when requestedvia 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 theirpower capabilities to the operating system. The following sections describethese capabilities and objects.

2.6.2.1  Power Resources and States

A device declares its support for a power state by listingthe set of power resources it requires in order to be in that state. ACPI PowerResources represent the voltage rails that power devices and the clock signalsthat 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 iscontrolled, and an _STA method to report its state. For more information, see section7.1, "Declaring a Power Resource Object", of the ACPI 5.0specification.

The operating system's ACPI driver monitors the powerdependencies among devices that share resources, and, as these devicestransition between power states, ensures that only the power resources that areactually 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 thedevice driver decides to transition to a new power state, the ACPI driverensures that any power resources required for the new state are turned on, andthat 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  Ifa particular platform supports the D3cold feature, and the device driver for adevice opts-in to D3cold, the device's _PR3 power resources will, if they are notbeing used by any other device, be turned off sometime after the transition toD3hot.

2.6.2.1.2  Device Power State (_PSx)

There is a Power State method, _PSx, where x = 0, 1, 2, or3, for each supported device power state Dx.This method is optional, but if it is present it is invoked before the powerresources for the state are turned off, and after the power resources for thestate are turned on. _PSx is intended to perform any platform-specific actionsrequired around the power cycle. _PSx must not access device registers that are assigned to the function driver, accessbus-standard registers that are assigned to the bus driver, or switch powerresources 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 whenin a low-power state and cause the platform to wake up to handle them. Toenable this feature, Windows needs information about the capabilities of boththe platform and the device.

2.6.2.2.1  Sx Device Wake State (_SxW)

On a given platform, there is a specific mapping betweendevice states that support the wake capability and system states that canrespond to wake events. ACPI defines the _SxWobject to provide this information to the operating system. There is an SxW object for each supported system powerstate, Sx. Since SoC platforms arealways in S0, the only object of interest here is _S0W. This object specifiesthe platform's ability to wake from a low-power idle state in response to adevice's wake signal. The object is used by Windows to determine the targetD-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 ACPI5.0 specification.

For most SoC platforms, devices are aggressively power-managedto the D3 state when idle, and the system is capable of waking from low-poweridle while the device is in this state. For such a system, the _S0W objectreturns 3 (or 4, if it also supports D3cold). However, any D-state can be designatedas the lowest-powered wake- capable state, and some device classes or buses usedifferent values. For instance, SDIO- and USB-connected devices use state D2for this state.

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

2.6.2.2.2  Wake-Capable Interrupts (_CRS)

The resource description for a device indicates that thedevice is capable of detecting and signaling a wake event by marking aninterrupt as "wake-capable" (either ExclusiveAndWake orSharedAndWake). Windows and device drivers provide special handling of suchinterrupts to ensure that they are enabled when the device transitions to alow-power state. For more information, see the descriptions of the Interrupt andGpioInt resource descriptors in section 6.4.3.6, "Extended InterruptDescriptor", and section 6.4.3.8.1 , "GPIO ConnectionDescriptors", of the ACPI 5.0 specification.

2.6.2.3  Wake Enablement

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

2.6.2.3.1  Device Sleep Wake (_DSW)

ACPI defines the _DSW object as a way for the operatingsystem to inform the ACPI platform firmware about the next sleep or low-poweridle period. This object is optional, and is used only if the platform has aneed to configure platform-specific wake hardware in advance. The targetD-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 informationprovided by the device's _SxWobject(s).

2.6.2.3.2  Power Resources for Wake (_PRW)

In some cases, there are additional power resources thatmust be turned on for a device to be enabled for wake. In this case, the devicecan provide the _PRW object to list those additional power resources. The operatingsystem'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, awake-enabled device), and are turned off otherwise.

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

2.7  ACPI-Defined Devices

ACPI defines a number of devices to represent and controltypical platform features. Examples are a power button, a sleep button, systemindicators, and so on. For more information, see section 9, "ACPI-DefinedDevices and Device-Specific Objects", of the ACPI 5.0 specification. Forthe target SoC platforms, the ACPI-defined devices described in the followingsections are supported by built-in drivers.

2.7.1  Lid Device

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

2.7.2  Control Method Battery Device

This device describes, configures, and reports the statusof the platform battery. For more information, see section 10.2, "ControlMethod Batteries", of the ACPI 5.0 specification. Control Method Battery implementationson SoC platforms use the GPIO-signaled ACPI event mechanism, which is describedin section 5.6.5, "GPIO-Signaled ACPI Events", of the ACPI 5.0specification. Access to the battery and charging hardware is done by methods thatoperate through GPIO or SPB OpRegions, which are described in sections5.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" whitepaper at http://msdn.microsoft.com/library/windows/hardware/jj248727.aspx.

2.7.2.1  Battery Device-Specific Method

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

·        Appendix A (section A.2, "BatteryDevice-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 theoptional control method-based Time and Alarm device, which provides a hardware-independentabstraction and a more robust alternative to the Real Time Clock (RTC). Formore information, see section 9.15, "PC/AT RTC/CMOS Devices", and section9.18, "Time and Alarm Device", of the ACPI 5.0 specification. If the standardPC RTC either is not implemented or is used as the RTC hardware backing the Timeand Alarm device, the "CMOS RTC Not Present" bit of the FADT's BootArchitecture flags field must be set.

The time capabilities of the Time and Alarm device arerequired for platforms that support the InstantGo feature (and the ConnectedStandby power mode). These capabilities maintain time-of-day information acrosssystem power transitions, and keep track of time even when the platform isturned off. It is expected that the time on the platform will be consistentwhen different firmware interfaces are used to query the platform time. Forexample, a UEFI call to get the time should return the same time that theoperating system would get by using the Time and Alarm device.

The Time and Alarm device must be driven from the sametime 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'sconcept of thermal zones. This is a cooperative firmware/OS/driver model thatabstracts the sensors and cooling devices from the central thermal managementcomponent through well-defined interfaces. For more information about thermalmanagement, see the document titled "Thermal Management in Windows"on the Microsoft Connect website at http://connect.microsoft.com/site1304/Downloads/DownloadDetails.aspx?DownloadID=48106.

2.7.4.2  ACPI Thermal Zones

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

?       Identify the devices contained in the thermal zone:

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

o  _PSL to list the processors in the thermal zone.

?       Specify thermal thresholds at which actions mustbe taken:

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

o  _HOT to indicate the temperature at which the operatingsystem hibernates.

o  _CRT to indicate the temperature at which the operatingsystem shuts down.

?       Describe the thermal zone's passive coolingbehavior:

o  _TC1, _TC2 for thermal responsiveness.

o  _TSP for the appropriate temperature samplinginterval 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 sensordriver and allocating hardware resources to it.

?       Optionally, receive notifications of additionaltemperature threshold crossings:

o  _NTT for specifying additional thresholdcrossings to be notified of.

o  _DTI for receiving notifications of additionalthreshold crossings.

?       Optionally, describe the thermal zone's ActiveCooling Behavior:

o  _ALx for listing the fans in the thermal zone.

o  _ACx the temperature at which fan x mustbe turned on.

For more information about ACPI thermal zones, see chapter11, "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 thatprocessor cores in the thermal zone should be idled (instead of throttled).This is done by including the Processor Aggregator device (ACPI000C) in one ormore 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 isgreater. For more information, see section 8.5.1, "Logical ProcessorIdling", in the ACPI 5.0 specification.

OEMs can include a Device-Specific Method (_DSM) tosupport the Microsoft thermal extensions for Windows. For more information, seeAppendix A (section A.3, "Device-Specific Method for Microsoft ThermalExtensions") later in this paper.

2.8  Other Namespace Objects

For some specific classes of device, there arerequirements for additional namespace objects to appear under those devices inthe 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, aswith other devices on the platform. Processor devices must contain thefollowing objects:

?       _HID : ACPI0007

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

2.8.2  Display-Specific Objects

For more information about display-specific objects, seeAppendix 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 forconnecting internal and external devices. Windows includes inbox drivers forstandard USB host controllers that are compliant with the EHCI or XHCIspecifications.

On SoC platforms, the USB host controller can beenumerated by ACPI. Windows uses the following ACPI namespace objects whenenumerating and configuring compatible USB hardware:

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

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

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

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

2.8.3.1  USB Device-Specific Method (_DSM)

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

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

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

The _HRV is set according to the following criteria:

?        NoIntegratedTT- _HRV = 0

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

?        IntegratedTTSpeedInPortSc- _HRV = 1

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

?        IntegratedTTSpeedInHostPc- _HRV = 2

o  Enable integrated TT support. This flavor ofinterface 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 HOSTPCregister 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 devicesconnected to XHCI controllers can be put into a D3cold state and powered offwhen not in use (see section 2.6, "Device Power Management", earlierin 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-abilityof USB Ports on the system. This is required in order to provide accurateinformation to the user about ports and devices. Two objects, Physical DeviceLocation (_PLD) and USB Port Capabilities (_UPC), are used for this purpose. Formore information, see the following:

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

·        The UsingACPI to Configure USB Ports on a Computer topic on MSDN

2.8.4 SD Host Controllers and Devices

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

On SoC platforms, the SD host controller can be enumeratedby ACPI. Windows uses the following ACPI Namespace objects when enumerating andconfiguring compatible SD Hardware:

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

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

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

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

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

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

o  For each slot, resources are listed in thefollowing order:

§  Thebase address of the SD standard register set for the slot

§  TheSD standard interrupt for the slot

§  AGPIO interrupt resource for the slot, for signaling card insertions andremovals (if the standard SD card-detect interface is not supported during allpower states).

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

§  Asecond 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 powerstates).

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 theACPI namespace as children of the SD host controller. This requirement enablesthe operating system to associate the bus-enumerated device with theplatform-specific attributes provided for the device by ACPI objects (forexample, 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 isdefined 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 (toindicate that the device cannot be removed).

?       A _CRS object for the sideband resources thedevice 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 orby USB. In either case, Windows needs to know the physical location of thecamera so that the appropriate UI can be shown. To do this, camera devices thatare 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 (nesteddevice) 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, "ACPINamespace Hierarchy and _ADR for Embedded USB Devices", below.

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

?       The camera device to provide the _PLD object.

?       If there are any sideband resources required bythe camera driver (such as GPIO interrupt or I/O connections, or an SPBconnection), 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. Allother fields are optional. For handheld mobile devices, including tablets, thefront panel is the one holding the display screen, and its origin is in thelower-left corner when the display is viewed in the portrait orientation. Usingthis reference, "Front" indicates that the camera views the user(webcam), while "Back" indicates that the camera views away from theuser (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 devicesenumerated by the Windows USB driver. This can be determined by examiningWindows Device Manager in its "View by Connection" mode. The entirehierarchy, starting from the USB host controller and extending down to theembedded device, must be included. The "Address" property provided inDevice Manager for each device is the address that the firmware must report inthe device's _ADR.

The ACPI 5.0 specification defines the addresses for USB devicesas 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 theaddress of that port.

If the device connected to a port is a composite USBdevice, 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 http://msdn.microsoft.com/library/windows/hardware/jj159307.aspx.

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) {...}

            }  //  Endof Camera device

    } // End ofRoot Hub Device

}  // End of EHCIdevice

2.8.5.2.2  A USB Composite device that implements a Webcam asFunction 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 afirst

                                  //  Interface number of 2, so

                                  //  Address is 3 + 2  = 5.

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

            }  //  Endof Camera device

        } // End ofComposite USB Device

    } // End ofRoot Hub Device

}  // End of EHCIdevice

2.8.5.2.3  A Webcam connected over I2C

Device (GPU0) {

    ... // Otherobjects required for graphics devices

    Name (_DOD,Package () // Identifies the children ofthis                                   //   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 deviceIDs (for

                                  //   example, display output ports)

                })

    Device (CAM0) {

        Name (_ADR,0x00024321)   // The identifier for thisdevice

                                  //  (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 ofCAM0 device

} // End of GPU0 device

2.8.6  HID-over-I2C Devices

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

?       A vendor-specific _HID

?       A _CID of PNP0C50

?       A _CRS with:

o  An I2CSerialBusConnection resource for access tothe device

o  A GpioInt resource for interrupt(s)

?       The HIDI2C _DSM method for returning the HIDDescriptor Register address within the device. For more information, seeAppendix A (section A.5, " HIDI2C Device-Specific Method (_DSM)", laterin this paper.

2.8.7  Button Devices

For SoC platforms, Windows supports both the ACPI-definedControl Method Power Button, as well as a Windows-compatible five-button array.The power button, whether implemented as an ACPI Control Method Power Button oras 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 whenheld down. For more information, see section 4.8.2.2.1.3, "Power ButtonOverride", of the ACPI 5.0 specification.

2.8.7.1  Control Method Power Button

Clamshell designs, and other systems with built-in orconnected keyboards, implement the ACPI-defined Control Method Power Button (section4.8.2.2.1.2 of the ACPI 5.0 specification) using GPIO-Signaled ACPI Events (section5.6.5 of the ACPI 5.0 specification). To support the power button device, thenamespace:

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

?       Lists the power button's GPIO interrupt resourcein 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 MethodButton driver in the operating system that the button event has occurred.

For more information, see the "Hardware Buttons forWindows 8 Tablet and Convertible Devices" white paper at http://msdn.microsoft.com/library/windows/hardware/hh975395.aspx.

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 inthe array has its defined function (see the numbered items in the list below),and certain "hold-and-press" button combinations have additionalmeaning in the UI. No button combinations are defined that require the powerbutton to be held down. For compatibility with the Windows inbox button driver,the Windows-compatible Button Array ACPI device is implemented. The device isdefined as follows:

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

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

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

?       The GPIO interrupt resources in the _CRS objectare 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

§  TheWindows 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 useExclusive).

5.      Interrupt corresponding to the "RotationLock" button, if supported

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

For more information, see the "Hardware Buttons forWindows 8 Tablet and Convertible Devices" white paper at http://msdn.microsoft.com/library/windows/hardware/hh975395.aspx.

To support evolution of the Windows Button UI, Windowsdefines a Device-Specific Method (_DSM) for the Windows Button Array device.For more information, see Appendix A (section A.6, "Windows Button ArrayDevice-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 aresupported by the Windows inbox button driver. Note that the same requirementsthat apply to the Button Array device also apply to these devices:

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

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

?       The GPIO controller driver must use ActiveBoth emulationprovided by the GPIO framework extension (GpioClx).

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

For more information about the inbox button driver, seethe "Hardware Buttons for Windows 8 Tablet and Convertible Devices"white paper at http://msdn.microsoft.com/library/windows/hardware/hh975395.aspx.

2.8.8.1  Dock Sensing Device

This device interrupts the system when a dock is attachedor unattached from the system. This mode change information is used to updatethe user input and output experience, as required. The device's namespacerequires:

?       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 PCswitches from tablet to clamshell form factor. This mode change information isused to update the user input and output experience, as required. The device'snamespace 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 appendixdefines the device-specific methods discussed in this paper.

A.1  GPIOController Device-Specific Method (_DSM)

As a means ofsupporting a variety of device-class-specific communications between the GPIOdriver 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:

·         FunctionIndex 0: The Standard Query Function that all _DSM methods are required toprovide.

·         FunctionIndex 1: The ActiveBoth Polarity Function, which informs the GPIO stack ofany ActiveBoth pins on the controller that are not asserted logic low. The GPIOStack assumes that ActiveBoth Pins are asserted logic low, so this functionallows the platform to override that default for specific pins.

A.1.1  Definition

The GUID for theGPIO controller _DSM method is defined to be:

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

A.1.2  Function0

Function 0 ofevery _DSM is a query function that returns the set of supported functionindexes, and is always required. For the definition of Function 0, see section9.14.1, "_DSM (Device Specific Method)", of the ACPI 5.0specification.

A.1.3  Function1

The parametersfor 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

#defineGPIO_CONTROLLER _DSM_REVISION_ID     0

Arg2: Function index for ActiveBoth asserted polarity:

#defineGPIO_CONTROLLER_DSM_ACTIVE_BOTH_POLARITY_FUNCTION_INDEX  1

Arg3: Package empty (not used)

Return:

APackage of integers, each of which is the controller-relative pin number of apin on the GPIO controller that is:

·        Defined to be an ActiveBoth interrupt, and

·        Whose asserted state is not logic low (inother 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 functionidentifier was passed in

    //

    //

    // GPIO CLX UUID

    //

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

    {

        switch(Arg2)

        {

            //

            // Function 0: Return supportedfunctions, based on

            //    revision

            //

            case(0)

            {

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

                return (Buffer() {0x3})

            }

            //

            // Function 1: For emulatedActiveBoth controllers,

            //    returns a package of controller-relativepin

            //    numbers. Each corresponding pin will havean

            //    initial polarity of ActiveHigh.

            //

            //    A pin number of 0xffff is ignored.

            //

            case(1)

            {    

                // Marks pins 0x28, 0x29 and0x44 to be ActiveHigh.

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

            }

            //

            // Unrecognized function for thisrevision

            //

            default

            {

                BreakPoint

            }

        }

    }

    else

    {

        //

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

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

        //are supported for this UUID.

        //

        return (Buffer() {0})

    }

}

A.2  BatteryDevice-Specific Method

To support thepassive thermal management of the battery by the platform, Microsoft defines a_DSM method to communicate to the platform firmware the thermal throttlinglimit set by the battery's thermal zone. For more information, see thediscussion of "Thermal Zones" in section 2.7.4 of this paper.

A.2.1  Function1: Battery Thermal Limit

The _DSM controlmethod parameters for the battery charging thermal limit function are asfollows:

Arguments:

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

Arg1: Revision = 0

Arg2: Function index = 1

Arg3: Thermal limit (integer value from0 to 100)

Return:

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

A.3  Device-SpecificMethod for Microsoft Thermal Extensions

To support moreflexible design of thermal zones  andthermal sensors, Windows supports extensions to the ACPI thermal zone model.Specifically, Windows supports a thermal minimum throttle limit (MTL) for eachthermal zone, and also supports sharing a temperature sensor between thermalzones. For more information about MTL, see the document titled "ThermalManagement in Windows" on the Microsoft Connect website at http://connect.microsoft.com/site1304/Downloads/DownloadDetails.aspx?DownloadID=48106.

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

A.3.1  Function1: Minimum Throttle Limit

The _DSM controlmethod 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:

Aninteger value with the current minimum throttle limit, expressed as apercentage. Windows will not set the throttle limit below this value.

A.3.2  Function2: Temperature Sensor Device

The _DSM controlmethod 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:

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

A.3.3  TemperatureSensor Device Dependency Requirement

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

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

A.4  USBDevice-Specific Method (_DSM)

To supportdevice-class-specific configuration of the USB subsystem, Windows defines aDevice-Specific Method (_DSM) with the following functions.

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

The _DSM controlmethod parameters for the post-reset processing function for dual-role USBcontrollers 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 inboxdrivers only support USB controllers in host mode. After each controller reset,the USB driver will invoke the _DSM function index 1 to perform anycontroller-specific initialization required to configure the USB controller tooperate in host mode.

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

A.4.2  Function2: Port Type Identification

The _DSM controlmethod 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:

Aninteger 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 thisfunction is used, the _DSM method must appear under the USB port device.

Note  Function index 0 ofevery _DSM is a query function that returnsthe set of supported function indexes, and is always required. For moreinformation, see section 9.14.1, "_DSM (Device Specific Method)", ofthe ACPI 5.0 specification.

A.5  HIDI2CDevice-Specific Method (_DSM)

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

For the HIDI2Cclass 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:

Aninteger containing the HidDescriptorAddress. This address is the registeroffset in the I2C device at which the HID descriptor(s) can be read.

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

A.6  WindowsButton Array Device-Specific Method (_DSM)

To supportevolution 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  Function1: Power Button Properties

The _DSM controlmethod 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:

Aninteger (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 powerbutton is configured to detect both press and release events, and to reportthese events to the operating system. Otherwise, this bit should be 0.

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

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

Note  Function index 0 ofevery _DSM is a query function that returnsthe set of supported function indexes, and is always required. For moreinformation, see section 9.14.1, "_DSM (Device Specific Method)", ofthe ACPI 5.0 specification.

Appendix B: GPIO Controller Requirements Checklist

This appendixsummarizes the hardware, firmware, and software requirements for GPIO controllerdevices that are exposed to Windows.

B.1  Hardware

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

o   Increasesreliability of Emulated ActiveBoth.

?       Level-mode interrupts are supported.

o   Requiredfor both Emulated ActiveBoth and Debounce Emulation features.

?       Both High and Low interrupt polarities aresupported.

o   Requiredfor both Emulated ActiveBoth and Debounce Emulation features.

?       Interrupt polarity can be re-programmed at runtime.

o   Requiredfor both Emulated ActiveBoth and Debounce Emulation features.

B.2  Firmware

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

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

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

?       GPIO controller _DSM included if any ActiveBothinterrupts connected to the controller are asserted logic high insteadof logic low.

?       Implement _REG methods for each GPIO controllerand prevent use of GeneralPurposeIO OpRegions if _REG indicates that the regionhandler is not available.

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

B.3  Driver

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

o   Implementthe CLIENT_QueryEnabledInterrupts callback function.

§ Greatly assists in diagnosing interrupt storms.

o   Ifthe BankIdlePowerMgmtSupported flagis set in the CONTROLLER_BASIC_INFORMATION structure, the GPIO controller driver mustimplement the CLIENT_SaveBankHardwareContext and CLIENT_RestoreBankHardwareContext callback functions, and these functionsmust save/restore bank context appropriately, including the masked/unmaskedstate of the interrupts. Note that interrupts are not guaranteed to bedisconnected at the time this function is called, but, if they are stillconnected, they are guaranteed to be masked.

o   Ifthe DeviceIdlePowerMgmtSupported flag is set in the CONTROLLER_BASIC_INFORMATION structure, the CLIENT_StartController and CLIENT_StopController callback functions must save/restorecontext for all banks appropriately, including the masked/unmasked state of theinterrupts. Note that interrupts are not guaranteed to be disconnectedat the time this function is called, but, if they are still connected, they areguaranteed to be masked.

?       Set the EmulateDebouncing flag in the CONTROLLER_BASIC_INFORMATION structure.

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

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

o   Ensuresreliable edge detection for ActiveBoth interrupts.

References and Resources

?       The AdvancedConfiguration and Power Interface Specification, Revision 5.0, is availableon the ACPI website at http://www.acpi.info.

?       For all firmware requirements, see the documentationfor the Windows Certification Program at http://msdn.microsoft.com/library/windows/hardware/gg463010.aspx.

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

?       The MicrosoftDebug Port Table 2 (DBG2) specification is available at http://msdn.microsoft.com/library/windows/hardware/hh673515.

?       For more information about the AMLI debugger andother ACPI debugging extensions, see the "ACPI Debugging" topic at http://msdn.microsoft.com/library/ff537808(v=VS.85).aspx.

?       For more information about configuring USBports, see the "Using ACPI to Configure USB Ports on a Computer"topic at http://msdn.microsoft.com/library/ff553550(v=VS.85).aspx.

?       For more information about reporting cameralocation, see the "Windows 8 Requirement: Identifying the Location ofInternal Cameras" white paper at http://msdn.microsoft.com/library/windows/hardware/jj159307.aspx.

?       For more information about battery management inWindows, see the "Windows Power and Battery Subsystem Requirements at http://msdn.microsoft.com/library/windows/hardware/jj248727.aspx.

?       For more information about the Windows buttondriver, see the "Hardware Buttons for Windows 8 Tablet and ConvertibleDevices" white paper at http://msdn.microsoft.com/library/windows/hardware/hh975395.aspx.