DXGKCB_POWERRUNTIMECONTROLREQUEST callback function (d3dkmddi.h)

Article
02/22/2024

A kernel-mode display miniport driver calls DXGKCB_POWERRUNTIMECONTROLREQUEST to exchange information with the Power Engine Plug-in (PEP).

Syntax

DXGKCB_POWERRUNTIMECONTROLREQUEST DxgkcbPowerruntimecontrolrequest;

NTSTATUS DxgkcbPowerruntimecontrolrequest(
  [in]           IN_CONST_HANDLE hAdapter,
  [in]           IN LPCGUID PowerControlCode,
  [in, optional] IN PVOID InBuffer,
  [in]           IN SIZE_T InBufferSize,
  [in, optional] OUT PVOID OutBuffer,
  [in]           IN SIZE_T OutBufferSize,
  [out]          OUT PSIZE_T BytesReturned
)
{...}

Parameters

[in] hAdapter

A handle to the display adapter. The display miniport driver receives the handle from the DeviceHandle member of the DXGKRNL_INTERFACE structure in a call to its DxgkDdiStartDevice function.

[in] PowerControlCode

A pointer to a GUID that defines the meaning of the display miniport driver's control request. For more information, see Remarks.

[in, optional] InBuffer

An optional pointer to an input buffer.

[in] InBufferSize

The size, in bytes, of the optional buffer that InBuffer points to. Set to zero if no InBuffer is provided.

[in, optional] OutBuffer

An optional pointer to an output buffer.

[in] OutBufferSize

The size, in bytes, of the optional buffer that OutBuffer points to. Set to zero if no OutBuffer is provided.

[out] BytesReturned

The number of actual bytes returned in the buffer that OutBuffer points to. The returned value will be <= OutBufferSize.

Return value

DXGKCB_POWERRUNTIMECONTROLREQUEST returns STATUS_SUCCESS if it succeeds. Otherwise, it returns one of the error codes defined in Ntstatus.h.

Remarks

Note

To avoid a possible deadlock, do not call the DXGKCB_SETPOWERCOMPONENTACTIVE function until this function has returned.

DXGKCB_XXX functions are implemented by Dxgkrnl. To use this callback function, call DxgkCbPowerRuntimeControlRequest via the DXGKRNL_INTERFACE.

Although the driver can use any GUID in the PowerControlCode parameter, the following GUIDs that are defined in D3dkmddi.h are recommended. By using these GUIDs, the display port driver can issue Event Tracing for Windows (ETW) events, which are useful to profile driver performance issues.

GUID	Meaning
GUID_DXGKDDI_POWER_VOLTAGE_UP	Increase the voltage.
GUID_DXGKDDI_POWER_VOLTAGE_DOWN	Decrease the voltage.
GUID_DXGKDDI_POWER_VOLTAGE	Change the voltage, but the driver doesn't know if the change is an increase or decrease.
GUID_DXGKDDI_POWER_CLOCK_UP	Increase the clock setting.
GUID_DXGKDDI_POWER_CLOCK_DOWN	Decrease the clock setting.
GUID_DXGKDDI_POWER_CLOCK	Change the clock setting, but the driver doesn't know if the change is an increase or decrease.
GUID_DXGKDDI_POWER_BANDWIDTH_UP	Increase the bandwidth.
GUID_DXGKDDI_POWER_BANDWIDTH_DOWN	Decrease the bandwidth.
GUID_DXGKDDI_POWER_BANDWIDTH	Change the bandwidth, but the driver doesn't know if the change is an increase or decrease.

These GUIDs do not imply that there is any communication protocol between the display miniport driver and the PEP, nor do they imply that there are any restrictions on the values that can be passed between the display miniport driver and the PEP.

Requirements

Requirement	Value
Minimum supported client	Windows 8 (WDDM 1.2)
Minimum supported server	Windows Server 2012
Target Platform	Desktop
Header	d3dkmddi.h (include D3dkmddi.h)
IRQL	<=DISPATCH_LEVEL