Hardware Dev Center

GetD3ColdCapability routine

The GetD3ColdCapability routine enables the driver for a device to query whether the device is capable of making a transition to the D3cold device power state.

Syntax


NTSTATUS GetD3ColdCapability(
  _In_opt_ PVOID    Context,
  _Out_    PBOOLEAN D3ColdSupported
);

Parameters

Context [in, optional]

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.

D3ColdSupported [out]

A pointer to a BOOLEAN variable to which the routine writes a value that indicates whether the underlying bus driver and ACPI system firmware support D3cold for this device. If this value is TRUE, D3cold is supported. If FALSE, D3cold is not supported. If the call fails, the routine returns an error status code and does not write anything to this variable.

Return value

The GetD3ColdCapability routine returns STATUS_SUCCESS if it successfully determines whether the device can enter D3cold. Otherwise, it returns an appropriate error status code.

Remarks

This routine indicates whether a device can enter the D3cold substate when the computer is in the S0 (working) system power state (and is not preparing to exit S0). This routine does not indicate what capabilities the device might have in D3cold. For example, to determine whether the device can signal a wake event from D3cold, call the GetIdleWakeInfo routine.

The driver for a device can call the SetD3ColdSupport routine to enable or disable transitions to D3cold. However, if the driver enables these transitions, such a transition never occurs if the device is not capable of entering D3cold. The GetD3ColdCapability routine reports whether the device has this capability.

For example, a graphics device might have a large hardware context, and take a long time to resume operation after a D3cold-to-D0 transition. This resume latency might be acceptable or unacceptable, depending on the set of tasks that the user is currently performing. Additionally, this latency might vary with the user's task mix. The driver for the device might need to dynamically enable and disable transitions to D3cold as the task mix changes. However, there is no need for the driver to go to this trouble if the GetD3ColdCapability routine indicates that the device is not capable of entering D3cold.

The drivers for many types of devices do not need the information provided by the GetD3ColdCapability routine. If a driver calls SetD3ColdSupport to enable transitions to D3cold, but the device is not capable of entering D3cold, this call has no effect, but is harmless.

Requirements

Target platform

Desktop

Version

Available starting with Windows 8.

Header

Wdm.h (include Wdm.h)

IRQL

PASSIVE_LEVEL

See also

D3COLD_SUPPORT_INTERFACE
GetIdleWakeInfo
SetD3ColdSupport

 

 

Send comments about this topic to Microsoft

Show:
© 2015 Microsoft