estructura PO_FX_DEVICE_V3 (wdm.h)

Artículo
02/27/2024

La estructura de PO_FX_DEVICE_V3 describe los atributos de energía de un dispositivo para el marco de administración de energía ( PoFx), DFx (Dirigido PoFx)

Sintaxis

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;

Miembros

Version

Número de versión de esta estructura. Si el controlador se registrará para obtener compatibilidad con energía dirigida con DFx, establezca este miembro en PO_FX_VERSION_V3.

Flags

Controla si los dispositivos secundarios directos y los dispositivos secundarios de energía pueden optar por no participar en Direct PoFx.

Entre los valores de marca posibles se incluyen:

Marca	Descripción
PO_FX_DEVICE_FLAG_DIRECT_CHILDREN_OPTIONAL	Permite que los dispositivos secundarios directos de este dispositivo admitan opcionalmente Direct PoFx. Si no se establece, todos los elementos secundarios directos deben admitir Direct PoFx para que este dispositivo admita totalmente Direct PoFx.
PO_FX_DEVICE_FLAG_POWER_CHILDREN_OPTIONAL	Permite que los dispositivos secundarios de energía de este dispositivo admitan opcionalmente Directed PoFx. Si no se proporciona, todos los elementos secundarios de energía deben admitir Directed PoFx para que este dispositivo admita totalmente Directed PoFx.
PO_FX_DEVICE_FLAG_DFX_CHILDREN_OPTIONAL	Establece PO_FX_DEVICE_FLAG_DIRECT_CHILDREN_OPTIONAL y PO_FX_DEVICE_FLAG_POWER_CHILDREN_OPTIONAL
PO_FX_DEVICE_FLAG_DISABLE_FAST_RESUME	Obliga a PoFx a evitar que el S0-IRP se complete antes de que D0-IRP se reanude desde un estado del sistema, como Hibernate o Sleep. Mutuamente excluyente con PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME.
PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME	Obliga a PoFx a permitir que el S0-IRP se complete antes de que D0-IRP se reanude desde un estado del sistema, como Hibernate o Sleep. Mutuamente excluyente con PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME.

ComponentActiveConditionCallback

Puntero a la rutina de devolución de llamada ComponentActiveConditionCallback implementada por el controlador de dispositivo.

ComponentIdleConditionCallback

Puntero a la rutina de devolución de llamada ComponentIdleConditionCallback implementada por el controlador de dispositivo.

ComponentIdleStateCallback

Puntero a la rutina de devolución de llamada ComponentIdleStateCallback implementada por el controlador de dispositivo.

DevicePowerRequiredCallback

Puntero a la rutina de devolución de llamada DevicePowerRequiredCallback implementada por el controlador de dispositivo.

DevicePowerNotRequiredCallback

Puntero a la rutina de devolución de llamada DevicePowerNotRequiredCallback implementada por el controlador de dispositivo.

PowerControlCallback

Puntero a la rutina de devolución de llamada powerControlCallback implementada por el controlador de dispositivo.

DirectedPowerUpCallback

Puntero a la rutina de devolución de llamada PO_FX_DIRECTED_POWER_UP_CALLBACK implementada por el controlador de dispositivo. Un dispositivo solo puede proporcionar las DirectedPower* devoluciones de llamada al registrarse para PoFx. No es necesario implementar el resto de las devoluciones de llamada de PoFx.

DirectedPowerDownCallback

Puntero a la rutina de devolución de llamada PO_FX_DIRECTED_POWER_DOWN_CALLBACK implementada por el controlador de dispositivo.

DirectedFxTimeoutInSeconds

Proporciona una sugerencia al marco que especifica un tiempo de espera recomendado en segundos en los que el dispositivo debe haber inactivo después de que la actividad de software ya no esté presente. El valor predeterminado es 2 minutos.

DeviceContext

Puntero a un contexto de dispositivo asignado por el autor de la llamada. Este puntero se pasa como parámetro a cada función de devolución de llamada implementada por el controlador a la que apunta esta estructura. El controlador de dispositivo usa este contexto para almacenar información sobre el estado de alimentación actual del dispositivo. Este contexto es opaco para PoFx.

ComponentCount

Número de elementos de la matriz Components . Además, este miembro especifica el número de componentes del dispositivo.

Components[ANYSIZE_ARRAY]

Este miembro es el primer elemento de una matriz de uno o varios elementos PO_FX_COMPONENT_V2. Si la matriz contiene más de un elemento, los elementos adicionales siguen inmediatamente la estructura PO_FX_DEVICE_V2 . La matriz contiene un elemento para cada componente del dispositivo. El estado de energía Fx de cada componente se puede controlar independientemente de los estados de potencia fx de los demás componentes del dispositivo. La constante ANYSIZE_ARRAY se define como 1 en el archivo de encabezado Ntdef.h.

Comentarios

Para registrar un dispositivo con PoFx, un controlador llama a la rutina PoFxRegisterDevice y proporciona, como parámetro, un puntero a una estructura de PO_FX_DEVICE que describe el dispositivo. Para usar PoFx, pero no DFx, regístrese en PoFx mediante PO_FX_DEVICE_V2 estructura o estructura PO_FX_DEVICE_V3.

Cada elemento de la matriz Components describe los atributos de estado de energía de un componente del dispositivo. Cada componente del dispositivo se identifica mediante su índice de matriz Components . Las rutinas como PoFxActivateComponent y PoFxCompleIdleCondition usan el índice de matriz de un componente para identificar el componente.

No se requiere un controlador de dispositivo para implementar las ocho rutinas de devolución de llamada. El controlador puede establecer un puntero de función en la estructura PO_FX_DEVICE en NULL si el controlador no implementa la rutina de devolución de llamada correspondiente. Sin embargo, se deben implementar ciertas rutinas de devolución de llamada. En concreto, si uno o varios componentes de un dispositivo tienen más de un estado Fx, el controlador debe implementar rutinas ComponentIdleStateCallback, ComponentActiveConditionCallback y ComponentIdleConditionCallback . De lo contrario, se produce un error en el registro del dispositivo y PoFxRegisterDevice devuelve STATUS_INVALID_PARAMETER.

Si un controlador no proporciona una de PO_FX_DEVICE_FLAG_DISABLE_FAST_RESUME o PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME el sistema se reservará a la configuración predeterminada de la plataforma. La configuración predeterminada es PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME para plataformas x86/x64 y PO_FX_DEVICE_FLAG_DISABLE_FAST_RESUME para plataformas ARM32/ARM64. Estas marcas solo se respetan para Win11 22000+ y se omiten silenciosamente para las versiones anteriores. Para los controladores WDF, estas marcas se pueden proporcionar mediante el campo PoFxDeviceFlags de WDF_POWER_FRAMEWORK_SETTINGS.