GET_D3COLD_CAPABILITY callback function (wdm.h)
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.
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 |