estrutura PO_FX_DEVICE_V3 (wdm.h)

Artigo
02/07/2025

A estrutura PO_FX_DEVICE_V3 descreve os atributos de energia de um dispositivo para a estrutura de gerenciamento de energia (PoFx), DFx (PoFx)

Sintaxe

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;

Membros

Version

O número de versão dessa estrutura. Se o driver se registrar para suporte de energia direcionado com DFx, defina esse membro como PO_FX_VERSION_V3.

Flags

Controla se dispositivos filho diretos e dispositivos filho de energia podem recusar o PoFx Direcionado.

Os valores de sinalizador possíveis incluem:

Bandeira	Descrição
PO_FX_DEVICE_FLAG_DIRECT_CHILDREN_OPTIONAL	Permite que dispositivos filho diretos desse dispositivo ofereçam suporte opcionalmente ao PoFx Direcionado. Se não estiver definido, todas as crianças diretas deverão dar suporte ao PoFx Direcionado para este dispositivo para dar suporte total ao PoFx Direcionado.
PO_FX_DEVICE_FLAG_POWER_CHILDREN_OPTIONAL	Permite que dispositivos filho de energia desse dispositivo ofereçam suporte opcionalmente ao PoFx Direcionado. Se não for fornecido, todas as crianças de energia deverão dar suporte ao PoFx Direcionado para este dispositivo para dar suporte total ao PoFx Direcionado.
PO_FX_DEVICE_FLAG_DFX_CHILDREN_OPTIONAL	Define PO_FX_DEVICE_FLAG_DIRECT_CHILDREN_OPTIONAL e PO_FX_DEVICE_FLAG_POWER_CHILDREN_OPTIONAL
PO_FX_DEVICE_FLAG_DISABLE_FAST_RESUME	Força a PoFx a impedir que o S0-IRP seja concluído antes que o D0-IRP seja retomado de um estado do sistema, como Hibernar ou Dormir. Mutuamente exclusivo com PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME.
PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME	Força a PoFx a permitir que o S0-IRP seja concluído antes que o D0-IRP seja retomado de um estado do sistema, como Hibernar ou Dormir. Mutuamente exclusivo com PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME.

ComponentActiveConditionCallback

Um ponteiro para o ComponentActiveConditionCallback rotina de retorno de chamada implementada pelo driver de dispositivo.

ComponentIdleConditionCallback

Um ponteiro para o ComponentIdleConditionCallback rotina de retorno de chamada implementada pelo driver de dispositivo.

ComponentIdleStateCallback

Um ponteiro para o ComponentIdleStateCallback rotina de retorno de chamada implementada pelo driver de dispositivo.

DevicePowerRequiredCallback

Um ponteiro para o DevicePowerRequiredCallback rotina de retorno de chamada implementada pelo driver de dispositivo.

DevicePowerNotRequiredCallback

Um ponteiro para o DevicePowerNotRequiredCallback rotina de retorno de chamada implementada pelo driver de dispositivo.

PowerControlCallback

Um ponteiro para o PowerControlCallback rotina de retorno de chamada implementada pelo driver de dispositivo.

DirectedPowerUpCallback

Um ponteiro para o PO_FX_DIRECTED_POWER_UP_CALLBACK rotina de retorno de chamada que é implementada pelo driver do dispositivo. Um dispositivo pode fornecer apenas os retornos de chamada DirectedPower* ao se registrar para PoFx. Ele não precisa implementar o restante dos retornos de chamada pofx.

DirectedPowerDownCallback

Um ponteiro para o PO_FX_DIRECTED_POWER_DOWN_CALLBACK rotina de retorno de chamada implementada pelo driver do dispositivo.

DirectedFxTimeoutInSeconds

Fornece uma dica para a estrutura especificando um tempo limite recomendado em segundos em que o dispositivo deve ter desocupado após a atividade de software não estar mais presente. O valor padrão é 2 minutos.

DeviceContext

Um ponteiro para um contexto de dispositivo alocado por chamador. Esse ponteiro é passado como um parâmetro para cada função de retorno de chamada implementada pelo driver que é apontada por essa estrutura. O driver do dispositivo usa esse contexto para armazenar informações sobre o estado de energia atual do dispositivo. Esse contexto é opaco para PoFx.

ComponentCount

O número de elementos na matriz componentes. Além disso, esse membro especifica o número de componentes no dispositivo.

Components[ANYSIZE_ARRAY]

Esse membro é o primeiro elemento em uma matriz de um ou mais elementos PO_FX_COMPONENT_V2. Se a matriz contiver mais de um elemento, os elementos adicionais seguirão imediatamente a estrutura PO_FX_DEVICE_V2. A matriz contém um elemento para cada componente no dispositivo. O estado de potência fx de cada componente pode ser controlado independentemente dos estados de energia fx dos outros componentes no dispositivo. A constante ANYSIZE_ARRAY é definida como 1 no arquivo de cabeçalho Ntdef.h.

Observações

Para registrar um dispositivo com PoFx, um driver chama o PoFxRegisterDevice rotina e fornece, como parâmetro, um ponteiro para uma estrutura PO_FX_DEVICE que descreve o dispositivo. Para usar o PoFx, mas não o DFx, registre-se no PoFx usando PO_FX_DEVICE_V2 estrutura ou PO_FX_DEVICE_V3 estrutura.

Cada elemento na matriz componentes descreve os atributos de estado de energia de um componente no dispositivo. Cada componente no dispositivo é identificado por seu índice de matriz componentes. Rotinas como PoFxActivateComponent e PoFxCompleteIdleCondition usam o índice de matriz de um componente para identificar o componente.

Um driver de dispositivo não é necessário para implementar todas as oito rotinas de retorno de chamada. O driver poderá definir um ponteiro de função na estrutura PO_FX_DEVICE como NULL se o driver não implementar a rotina de retorno de chamada correspondente. No entanto, determinadas rotinas de retorno de chamada devem ser implementadas. Especificamente, se um ou mais componentes em um dispositivo tiver mais de um estado Fx, o driver deverá implementar componentIdleStateCallback, ComponentActiveConditionCallbacke rotinas de ComponentIdleConditionCallback. Caso contrário, o registro do dispositivo falhará e PoFxRegisterDevice retornará STATUS_INVALID_PARAMETER.

Se um driver não fornecer um dos PO_FX_DEVICE_FLAG_DISABLE_FAST_RESUME ou PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME o sistema fará fallback para a configuração padrão da plataforma. A configuração padrão é PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME para plataformas x86/x64 e PO_FX_DEVICE_FLAG_DISABLE_FAST_RESUME para plataformas ARM32/ARM64. Esses sinalizadores são homenageados apenas pelo Win11 22000+ e são silenciosamente ignorados para versões anteriores. Para drivers WDF, esses sinalizadores podem ser fornecidos usando o campo PoFxDeviceFlags de WDF_POWER_FRAMEWORK_SETTINGS.