Device management namespace objects

The ACPI 5.0 specification defines several types of namespace objects that can be used to manage devices. For example, device identification objects contain identification information for devices that connect to buses, such as I2C, that do not support hardware enumeration of child devices. Other types of namespace objects can specify system resources, describe device dependencies, and indicate which devices can be disabled.

Device identification in Windows

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

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

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

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

Device identification in ACPI

Hardware ID (_HID)

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

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

Compatible ID (_CID)

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

Compatible ID	Description
PNP0C40	Windows-compatible button array
PNP0C50	HID-over-IВІC 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

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

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

For serviceability, there is a Windows Hardware Certification Kit (HCK) requirement that device IDs on OEM systems be «four-part» IDs. The four parts are the vendor ID, the device ID, the subsystem vendor (OEM) ID, and the subsystem (OEM) device ID. Therefore, the Subsystem ID (_SUB) object is required for OEM platforms.

Device-Specific Method (_DSM)

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

Address (_ADR) and Unique ID (_UID)

There are three additional requirements for device identification:

• For devices that connect to a hardware-enumerable parent bus (for example, SDIO, USB HSIC), but that have platform-specific features or controls (for example, sideband power or wake interrupt), the _HID is not used. Instead, the device identifier is created by the parent bus driver (as discussed previously). In this case, though, the Address Object (_ADR) is required to be in the ACPI namespace for the device. This object enables the operating system to associate the bus-enumerated device with its ACPI-described features or controls.
• On platforms where multiple instances of a particular IP block are used, so that each block has the same device identification objects, the Unique Identifier (_UID) object is necessary to enable the operating system to distinguish between blocks.
• No two devices in a particular namespace scope can have the same name.

Device configuration objects

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

New for SoC platforms are GPIO and simple peripheral bus (SPB) resources that a device can consume. For more information, see General Purpose I/O (GPIO) and Simple Peripheral Bus (SPB).

Also new for SoC platforms is a general-purpose fixed DMA descriptor. The FixedDMA descriptor supports the sharing of DMA controller hardware by a number of system devices. The DMA resources (request line and channel registers) statically allocated to a particular system device are listed in the FixedDMA descriptor. For more information, see section 19.5.49, «FixedDMA (DMA Resource Descriptor Macro)», of the ACPI 5.0 specification.

Device status changes

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

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

Enable/disable

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

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

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

• _STA must clear the «enabled and decoding its resources» bit whenever the device is disabled.
• The device must provide the Set Resource Settings (_SRS) object to re-enable the device hardware and set the above bit in _STA.

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

Device dependencies

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

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

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

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

There can also be software dependencies between device drivers. These dependencies must also be described.

For more information, see the following resources:

For driver-load-order dependencies, see Specifying Driver Load Order.

For power-relations dependencies, see:

IoInvalidateDeviceRelations (To trigger establishing power relations, call the IoInvalidateDeviceRelations routine with the DEVICE_RELATION_TYPE enum value PowerRelations.)

Generate ACPI tables by using AcpiGenFx

Microsoft supports a diverse and inclusive environment. This article contains references to terminology that the Microsoft style guide for bias-free communication recognizes as exclusionary. The word or phrase is used in this article for consistency because it currently appears in the software. When the software is updated to remove the language, this article will be updated to be in alignment.

Summary

• Create a .NET app that uses AcpiGenFx to generate ACPI tables

Applies to

Windows SoC and platform bring-up

Important APIs

Open AcpiGenFx in Object Browser

Use the IntelliSense feature in Visual Studio to determine methods and properties

Use the ACPI Generation Framework (AcpiGenFx) library to write an app that generates ACPI tables.

In Windows 10, the new C# library, AcpiGenFx, makes it easier for you to write an app that creates ACPI tables that describe the hardware devices and resources on the platform, such as interrupt controllers, SD host controllers, GPIO, and I 2 C devices. By using the methods and properties exposed by the framework objects, you can describe devices, resources, and dependencies without knowing the exact syntax of the ACPI table or referring to the ACPI specification. Not only does AcpiGenFx generate ACPI Machine Language (ASL) code that is OS-independent, it is also aware of Windows-specific requirements.

The app generates the relevant ACPI table files (*.aslc and *.asl) based on those descriptions. At build time, AcpiGenFx statically analyzes the platform description, detecting errors like cyclical or unresolved dependencies, device naming and UUID conflicts, resource to controller mappings, and much more. As a result, the generated ASL code is easier to debug because AcpiGenFx checks for the most common mistakes, and abstracts unique ACPI implementation details.

AcpiGenFx is declarative in nature: its output is static data only, and it is not designed to generate dynamic runtime methods. If a use case is not covered by the framework, such as advanced off-SoC peripheral device power management, the methods must be either implemented in a Windows Platform Extension driver or manually added to the AcpiGenFx-generated ASL code.

Before you begin

Locate the following files in the AcpiGenFx folder of your WDK installation.

AcpiGenFx.dll and associated samples are available in the Tools folder of the WDK. In the Tools directory, navigate to the target architecture folder, then to the AcpiGenFx folder. For example, the x86 version is located in C:\Program Files (x86)\Windows Kits\10\Tools\x86\ACPIGenFx.

Required to use ACPIGenFx.

Use this project as a starting point to design the ACPI firmware for the entire platform. The output is a full set of ACPI tables including the DSDT, FADT, and MADT.

Use this project as a starting point to add a peripheral device to an existing system. The sample demonstrates how to describe a sensor device and its resources. The output is an ACPI SSDT table in ASL.

Download Windows 10 kits, tools, and code samples.

Create a platform

In Visual Studio, open a new C# console project.

Add a reference to the AutoAcpi.dll assembly. Under the Project menu, click Add Reference. Click Browse and navigate to the location of AutoAcpi.dll. Click OK.

In Solution Explorer, expand References and select acpigenfx. View the objects in Object Browser (View > Object Browser).

Target .NET Framework 4.5 or later. Open project properties. On the Application page, make sure Target framework is set to .NET Framework 4.5.

Add the Using directive for the AutoAcpi object at the beginning of the code for the application.

Create a platform object. Based on your architecture, instantiate a Platform object by calling Platform.CreateArmPlatform or Platform.Createx86Platform. Specify OEMID, OEMTableID, Creator, Revision, and FileName.

Call Platform.WriteAsl to write to a file.

This example shows how to instantiate the platform.

Click Start to build and run your app. Visual Studio displays build progress in the Output window. (If the Output window is not visible, choose Output from the View menu.).

Open the folder named under project\bin\Debug or Release\Output. The Output folder contains files generated by the app. View the contents of SSDT.asl.

Here is the output of the preceding example.

The app generates two additional folders: Aslc and Bin. Aslc contains all the firmware tables in the aslc format. Bin contains all the firmware tables in the binary blob format.

Compile the ASL code files to an ACPI Machine Language (AML) binary by using the asl.exe compiler provided in the WDK.

Add devices and resources in the DSDT

You can add components to the platform. Typically, those components include processors, bus controllers, power resources, and so on. Here are some components that are used in DSDTSamples.

Platform.AddBatteryDevice

BatteryDevice.ThermalLimit

Platform.AddButtonArrayDevice

ButtonArrayDevice.AddBackButton

ButtonArrayDevice.AddCameraShutterButton

ButtonArrayDevice.AddCameraAutofocusButton

ButtonArrayDevice.AddGenericButton

ButtonArrayDevice.AddPowerButton

ButtonArrayDevice.AddRotationLockButton

ButtonArrayDevice.AddSearchButton

ButtonArrayDevice.AddVolumeDownButton

ButtonArrayDevice.AddVolumeUpButton

ButtonArrayDevice.AddWindowsHomeButton

Processor

ProcessorAggregator

Platform.AddProcessor

Platform.AddProcessorAggregator

XhciUsbController

EhciUsbController

UsbDevice

Platform.AddEhciUsbController

Platform.AddXhciUsbController

EhciUsbController.AddUsbDevice

XhciUsbController.AddUsbDevice

UsbDevice.AddUsbDevice

Object type	Creation method	Component
ACAdapter	Platform.AddACAdapter	Add an AC adapter.
BatteryDevice	Add a battery device and specify its thermal limit.
ButtonArrayDevice	Add buttons such as Windows Home, Back, Volume +/-, Power, Rotation Lock, and Search.
DisplaySensor	Platform.AddDisplaySensor	Add a display sensor.
GenericDevice	Platform.AddGenericDevice	Add a generic device that can be used to replace any type of internally supported device in the framework.
GpioController	Platform.AddGpioController	Add GPIO controllers and associated resources such as interrupts, I/O, and events.
HidOverI2C	Platform.AddHidI2CDevice	Add a HID device connected to the I 2 C bus.
I2CController	Platform.AddI2CController	Add I 2 C controllers and associated resources such as interrupts, I/O, and events.
KDNet2Usb	Platform.AddKDNet2Usb	Add support for kernel debugging by using Kdnet over USB.
PEPDevice	Platform.AddPepDevice	Add PEP devices and their resources and methods that return packages and static types.
Add processors and processor aggregators.
RTCDevice	Platform.AddRTCDevice	Add ACPI time and alarm devices.
SdHostController	Platform.AddSdHostController	Add SD host controllers.
SerialPort	Platform.AddSerialPort	Add support for serial and UART devices.
ThermalZone	Platform.AddThermalZone	Add thermal zones and associated sampling and polling periods.
Add USB host controllers and the child devices (including hubs).

To view the complete list, open AcpiGenFx in Object Browser. Use IntelliSense to determine the methods (and the parameters) and properties exposed by the objects. For example code that shows how to add the classes and set properties that are listed in the preceding table, refer to the DSDTSamples project.

Add debug support

To set a port as debuggable, set the DebugEnabled property on the object to «true».

For example, you might want to describe an xHCI host controller with USB debug port. In your app, call Platform.AddXhciUsbController to get an XhciUsbController object and set the DebugEnabled property to «true». AcpiGenFx generates a Microsoft DBG2 table that is automatically included in the app’s Output\Aslc folder.

Here is an example of how to add an xHCI host controller and declare it as debuggable.

In the preceding snippet, the xHCI host controller has interrupt resources and debug support. It has dependencies on a PEP device and a GPIO controller. To see descriptions of those devices, see DSDTSamples.

This example shows how to add an I 2 C controller to the DSDT.

Here is the output of the console app with the preceding definition for xHCI host and I 2 C controllers.

After building the project, in the project directory navigate to Output\Aslc. The Dbg2.aslc file contains the DB2 table shown here:

Add an ACPI description for a peripheral device in the SSDT

Create a platform object by calling Platform.CreateArmPlatform or Platform.Createx86Platform.

Set the SSDT property to true. This indicates to the framework that this table is an SSDT.

Create a device and assign resources. For example, for the sensor device shown here, the sample calls Platform.AddGenericDevice and specifies the device name, hardware ID, and unique instance. The sensor device that connects to the I 2 C serial bus, I2C1, which is described in the DSDT.

Here is the output of the preceding example.

Replacing ACPI firmware during development and testing

In development and test scenarios, you can replace the AML binary that is generated from the asl.exe compiler on the device. To do this, rename the AML binary to acpitabl.dat and move it to %windir%\system32. At boot time, Windows replaces tables present in the ACPI firmware with those in acpitabl.dat.

Make sure that test signing is enabled with the command: