PoFxIssueComponentPerfStateChange function (wdm.h)

The PoFxIssueComponentPerfStateChange routine submits a request to place a device component in a particular performance state.

Syntax

void PoFxIssueComponentPerfStateChange(
  [in] POHANDLE                 Handle,
  [in] ULONG                    Flags,
  [in] ULONG                    Component,
  [in] PPO_FX_PERF_STATE_CHANGE PerfChange,
  [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.

[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] PerfChange

A pointer to a PO_FX_PERF_STATE_CHANGE structure that represents the new performance state of the component.

[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

When a driver calls PoFxIssueComponentPerfStateChange, the power management framework (PoFx) requests the platform extension plug-in (PEP) to place the component's performance state set in the specified performance state. 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 PoFxIssueComponentPerfStateChange call is synchronous. In this case, PoFxIssueComponentPerfStateChange 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 PoFxIssueComponentPerfStateChange, and PoFxIssueComponentPerfStateChange returns only after the ComponentPerfStateCallback callback returns.

If Flags = PO_FX_FLAG_ASYNC_ONLY, the PoFxIssueComponentPerfStateChange call is asynchronous. In this case, PoFxIssueComponentPerfStateChange 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 PoFxIssueComponentPerfStateChange 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 PoFxIssueComponentPerfStateChange 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 state, the driver must wait until receiving the callback before committing the performance state to hardware.

Only a single call of the PoFxIssueComponentPerfStateChange 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

See also

ComponentPerfStateCallback

Device Performance State Management

PO_FX_PERF_STATE_TYPE

PoFxIssueComponentPerfStateChangeMultiple

PoFxRegisterComponentPerfStates