PoFxIssueComponentPerfStateChangeMultiple function (wdm.h)

Article
02/25/2022

The PoFxIssueComponentPerfStateChangeMultiple routine submits a request to change the performance states in multiple performance state sets simultaneously for a device component.

Syntax

void PoFxIssueComponentPerfStateChangeMultiple(
  [in] POHANDLE                   Handle,
  [in] ULONG                      Flags,
  [in] ULONG                      Component,
  [in] ULONG                      PerfChangesCount,
  [in] PO_FX_PERF_STATE_CHANGE [] PerfChanges,
  [in] PVOID                      Context
);

Parameters

[in] Handle

A handle that represents the registration of the device with PoFx. The device driver previously received this handle from the PoFxRegisterDevice routine.

[in] Flags

The flags that modify the behavior of the performance state change operation. Set this member to zero or to one of the following flag PO_FX_FLAG_XXX bits:

These two flag bits are mutually exclusive. For more information, see Remarks.

Value	Meaning
PO_FX_FLAG_BLOCKING 0x1	Make the condition change synchronous. If this flag is set, the routine that requests the condition change does not return control to the calling driver until the component hardware completes the transition to the new condition. This flag can be used only if the caller is running at IRQL < DISPATCH_LEVEL.
PO_FX_FLAG_ASYNC_ONLY 0x2	Make the condition change fully asynchronous. If this flag is set, the calling driver's callback routine is called from a thread other than the thread in which the routine that requests the condition change is called. Thus, the routine that requests the condition change always returns asynchronously without waiting for the callback to complete.

[in] Component

The index that identifies the component. This parameter is an index into the Components array in the PO_FX_DEVICE structure that the device driver used to register the device with PoFx. If the Components array contains N elements, component indexes range from 0 to N–1.

[in] PerfChangesCount

The number of performance state change requests contained in the PerfChanges array.

[in] PerfChanges

The first element in an array of PO_FX_PERF_STATE_CHANGE structures that represent the performance states the driver intends to transition to. Each array element represents a single performance state change request.

[in] Context

A pointer to the context for the ComponentPerfStateCallback callback routine. This parameter is optional. It is provided so that a driver or device context can be passed to the callback routine. If this parameter is not used, it must be set to NULL.

Return value

None

Remarks

A driver calls PoFxIssueComponentPerfStateChangeMultiple, the power management framework (PoFx) will request the platform extension plug-in (PEP) to place the component's performance state sets in the specified performance states. This routine may be used with both discrete and range-based types of performance state sets. For more information about discrete and range-based performance state sets, see PO_FX_PERF_STATE_TYPE.

If Flags = PO_FX_FLAG_BLOCKING, the PoFxIssueComponentPerfStateChangeMultiple call is synchronous. In this case, PoFxIssueComponentPerfStateChangeMultiple waits to return until the component completes the performance state transition. The driver's ComponentPerfStateCallback routine is called to inform the driver that the component's performance state change is complete. This callback occurs in the same thread as the call to PoFxIssueComponentPerfStateChangeMultiple, and PoFxIssueComponentPerfStateChangeMultiple returns only after the ComponentPerfStateCallback callback returns.

If Flags = PO_FX_FLAG_ASYNC_ONLY, the PoFxIssueComponentPerfStateChangeMultiple call is asynchronous. In this case, PoFxIssueComponentPerfStateChangeMultiple schedules the ComponentPerfStateCallback routine to occur in another thread, and then returns without waiting for the callback to occur. The callback can occur before or after PoFxIssueComponentPerfStateChangeMultiple returns. The driver should rely on the ComponentPerfStateCallback routine to determine when the component completes the transition to the new performance state.

The driver can set Flags = 0 to indicate that it does not care whether the PoFxIssueComponentPerfStateChangeMultiple call is synchronous or asynchronous. In this case, PoFx decides the synchronicity of the call based on whether the PEP uses a synchronous or asynchronous request to issue the performance state change to the component.

If Flags = PO_FX_FLAG_ASYNC_ONLY or no flags are passed, this routine requires an IRQL of <= DISPATCH_LEVEL. If Flags = PO_FX_FLAG_BLOCKING, this routine requires an IRQL of <= APC_LEVEL.

This function will always result in a call to the ComponentPerfStateCallback routine regardless of the synchronicity of the call. Because the PEP may choose to deny the request to change the performance states, the driver must wait until receiving the callback before committing the performance states to hardware.

Only a single call of the PoFxIssueComponentPerfStateChangeMultiple routine is allowed at a time per component, regardless of whether the call is synchronous or asynchronous. After issuing a performance state change request, the driver must wait until the ComponentPerfStateCallback is received before calling this routine again, even if the request involves a different performance state set. If this routine is called again before waiting until the ComponentPerfStateCallback is received, a bugcheck will occur.

Requirements

Requirement	Value
Minimum supported client	Available starting with Windows 10.
Target Platform	Universal
Header	wdm.h
Library	Ntoskrnl.lib
DLL	Ntoskrnl.exe
IRQL	<= APC_LEVEL or <= DISPATCH_LEVEL (See Remarks section)