PO_FX_DEVICE_V3 structure

The PO_FX_DEVICE_V3 structure describes the power attributes of a device to the power management framework (PoFx), DFx (Directed PoFx)

Syntax

typedef struct _PO_FX_DEVICE_V3 {
  ULONG                                      Version;
  ULONGLONG                                  Flags;
  PPO_FX_COMPONENT_ACTIVE_CONDITION_CALLBACK ComponentActiveConditionCallback;
  PPO_FX_COMPONENT_IDLE_CONDITION_CALLBACK   ComponentIdleConditionCallback;
  PPO_FX_COMPONENT_IDLE_STATE_CALLBACK       ComponentIdleStateCallback;
  PPO_FX_DEVICE_POWER_REQUIRED_CALLBACK      DevicePowerRequiredCallback;
  PPO_FX_DEVICE_POWER_NOT_REQUIRED_CALLBACK  DevicePowerNotRequiredCallback;
  PPO_FX_POWER_CONTROL_CALLBACK              PowerControlCallback;
  PPO_FX_DIRECTED_POWER_UP_CALLBACK          DirectedPowerUpCallback;
  PPO_FX_DIRECTED_POWER_DOWN_CALLBACK        DirectedPowerDownCallback;
  ULONG                                      DirectedFxTimeoutInSeconds;
  PVOID                                      DeviceContext;
  ULONG                                      ComponentCount;
  PO_FX_COMPONENT_V2                         Components[ANYSIZE_ARRAY];
} PO_FX_DEVICE_V3, *PPO_FX_DEVICE_V3;

Members

Version

The version number of this structure. If the driver will register for directed power support with DFx, set this member to PO_FX_VERSION_V3.

Flags

Controls whether direct child devices and power child devices can opt out of Directed PoFx.

Possible flag values include:

Flag Description
PO_FX_DEVICE_FLAG_DIRECT_CHILDREN_OPTIONAL Allows direct child devices of this device to optionally support Directed PoFx. If not set, all direct children must support Directed PoFx for this device to fully support Directed PoFx.
PO_FX_DEVICE_FLAG_POWER_CHILDREN_OPTIONAL Allows power child devices of this device to optionally support Directed PoFx. If not provided, all power children must support Directed PoFx for this device to fully support Directed PoFx.
PO_FX_DEVICE_FLAG_DFX_CHILDREN_OPTIONAL Sets both PO_FX_DEVICE_FLAG_DIRECT_CHILDREN_OPTIONAL and PO_FX_DEVICE_FLAG_POWER_CHILDREN_OPTIONAL

ComponentActiveConditionCallback

A pointer to the ComponentActiveConditionCallback callback routine that is implemented by the device driver.

ComponentIdleConditionCallback

A pointer to the ComponentIdleConditionCallback callback routine that is implemented by the device driver.

ComponentIdleStateCallback

A pointer to the ComponentIdleStateCallback callback routine that is implemented by the device driver.

DevicePowerRequiredCallback

A pointer to the DevicePowerRequiredCallback callback routine that is implemented by the device driver.

DevicePowerNotRequiredCallback

A pointer to the DevicePowerNotRequiredCallback callback routine that is implemented by the device driver.

PowerControlCallback

A pointer to the PowerControlCallback callback routine that is implemented by the device driver.

DirectedPowerUpCallback

A pointer to the PO_FX_DIRECTED_POWER_UP_CALLBACK callback routine that is implemented by the device driver. A device can provide only the DirectedPower* callbacks when registering for PoFx. It does not need to implement the rest of the PoFx callbacks.

DirectedPowerDownCallback

A pointer to the PO_FX_DIRECTED_POWER_DOWN_CALLBACK callback routine that is implemented by the device driver.

DirectedFxTimeoutInSeconds

Provides a hint to the framework specifying a recommended timeout in seconds in which the device should have idled out after software activity is no longer present. The default value is 2 minutes.

DeviceContext

A pointer to a caller-allocated device context. This pointer is passed as a parameter to each driver-implemented callback function that is pointed to by this structure. The device driver uses this context to store information about the current power state of the device. This context is opaque to PoFx.

ComponentCount

The number of elements in the Components array. Additionally, this member specifies the number of components in the device.

Components

This member is the first element in an array of one or more PO_FX_COMPONENT_V2 elements. If the array contains more than one element, the additional elements immediately follow the PO_FX_DEVICE_V2 structure. The array contains one element for each component in the device. The Fx power state of each component can be controlled independently of the Fx power states of the other components in the device. The ANYSIZE_ARRAY constant is defined to be 1 in the Ntdef.h header file.

Remarks

To register a device with PoFx, a driver calls the PoFxRegisterDevice routine and supplies, as a parameter, a pointer to a PO_FX_DEVICE structure that describes the device. To use PoFx but not DFx, register with PoFx using either PO_FX_DEVICE_V2 structure or PO_FX_DEVICE_V3 structure.

Each element in the Components array describes the power state attributes of one component in the device. Each component in the device is identified by its Components array index. Routines such as PoFxActivateComponent and PoFxCompleteIdleCondition use the array index of a component to identify the component.

A device driver is not required to implement all eight callback routines. The driver can set a function pointer in the PO_FX_DEVICE structure to NULL if the driver does not implement the corresponding callback routine. However, certain callback routines must be implemented. Specifically, if one or more components in a device has more than one Fx state, the driver must implement ComponentIdleStateCallback, ComponentActiveConditionCallback, and ComponentIdleConditionCallback routines. Otherwise, device registration fails and PoFxRegisterDevice returns STATUS_INVALID_PARAMETER.

Requirements

   
Minimum supported client Windows 10, version 1903
Header wdm.h

See Also

https://review.docs.microsoft.com/en-us/windows-hardware/drivers/kernel/introduction-to-the-directed-power-management-framework?branch=kernel_19h1

ComponentActiveConditionCallback

ComponentIdleConditionCallback

ComponentIdleStateCallback

DevicePowerNotRequiredCallback

DevicePowerRequiredCallback

PO_FX_COMPONENT

PoFxActivateComponent

PoFxCompleteIdleCondition

PoFxRegisterDevice

PowerControlCallback