GET_D3COLD_CAPABILITY callback function (wdm.h)

Article
02/25/2022

The GetBusDriverD3ColdSupport routine enables the driver for a device to query whether the enumerating bus driver supports the D3cold device power state.

Syntax

GET_D3COLD_CAPABILITY GetD3coldCapability;

NTSTATUS GetD3coldCapability(
  [in, optional] PVOID Context,
  [out]          PBOOLEAN D3ColdSupported
)
{...}

Parameters

[in, optional] Context

A pointer to interface-specific context information. The caller sets this parameter to the value of the Context member of the D3COLD_SUPPORT_INTERFACE structure for the interface.

[out] D3ColdSupported

A pointer to a BOOLEAN variable to which the routine writes a value to indicate whether the bus driver supports the D3cold. If this value is TRUE, the bus driver supports D3cold. If FALSE, the bus driver does not support D3cold. If the call fails, the routine returns an error status code and does not write anything to this variable.

Return value

The GetBusDriverD3ColdSupport routine returns STATUS_SUCCESS if it is successful. Otherwise, it returns an appropriate error status code.

Remarks

The driver for the device calls the version of this routine that is implemented by the Windows ACPI driver, Acpi.sys. This routine checks the parent bus driver for the device to determine whether this bus driver supports the D3cold power state.

For example, starting with Windows 8, Microsoft supplies an inbox USB 3.0 eXtensible Host Controller Interface (xHCI) driver that supports D3cold. Some third-party hardware vendors supply Windows drivers for their xHCI controllers, but these drivers might not support D3cold. The driver for a USB 3.0 device can call the GetBusDriverD3ColdSupport routine to determine whether the parent xHCI controller driver supports D3cold.

A bus driver supports D3cold if all of the following are true:

The bus driver implements the GUID_D3COLD_SUPPORT_INTERFACE driver interface.
The bus driver implements the GetBusDriverD3ColdSupport routine in this interface.
The output value from the GetBusDriverD3ColdSupport routine indicates that the bus driver supports D3cold.

The driver for a device can call the GetIdleWakeInfo routine to determine whether the underlying bus drivers and ACPI system firmware support D3cold for the device. If this call fails and returns an error status code, the device driver can call the GetBusDriverD3ColdSupport routine to determine whether the failure is caused by lack of D3cold support by the parent bus driver.

A device on a bus can make a transition to the D3cold substate only if the bus driver supports this transition. If the bus driver does not support D3cold, the device never enters D3cold, even if the function driver for the device calls the SetD3ColdSupport routine to enable the transition to D3cold. In this case, SetD3ColdSupport calls have no effect, but are harmless.

For this reason, most device drivers never need to call the GetBusDriverD3ColdSupport routine.

Requirements

Requirement	Value
Minimum supported client	Available starting with Windows 8.
Target Platform	Desktop
Header	wdm.h (include Wdm.h)
IRQL	PASSIVE_LEVEL