estrutura PO_FX_DEVICE_V3 (wdm.h)

Artigo
02/27/2024

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

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 o 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:

Sinalizador	Descrição
PO_FX_DEVICE_FLAG_DIRECT_CHILDREN_OPTIONAL	Permite que dispositivos filho diretos deste dispositivo deem suporte opcionalmente ao PoFx Direcionado. Se não estiver definido, todos os filhos diretos 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 avançados deste dispositivo deem suporte opcionalmente ao PoFx Direcionado. Se não for fornecido, todos os filhos 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 o 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 o PoFx a permitir que o S0-IRP seja concluído antes do D0-IRP no currículo de um estado do sistema, como Hibernar ou Dormir. Mutuamente exclusivo com PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME.

ComponentActiveConditionCallback

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

ComponentIdleConditionCallback

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

ComponentIdleStateCallback

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

DevicePowerRequiredCallback

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

DevicePowerNotRequiredCallback

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

PowerControlCallback

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

DirectedPowerUpCallback

Um ponteiro para o PO_FX_DIRECTED_POWER_UP_CALLBACK rotina de retorno de chamada implementada pelo driver do dispositivo. Um dispositivo só pode fornecer os DirectedPower* retornos de chamada ao se registrar no 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 que especifica um tempo limite recomendado em segundos em que o dispositivo deve ter ocioso 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 pelo 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 Components . 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.

Comentários

Para registrar um dispositivo com PoFx, um driver chama a rotina PoFxRegisterDevice 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 estrutura PO_FX_DEVICE_V3.

Cada elemento na matriz Components descreve os atributos de estado de energia de um componente no dispositivo. Cada componente no dispositivo é identificado pelo í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 rotinas ComponentIdleStateCallback, ComponentActiveConditionCallback e ComponentIdleConditionCallback . Caso contrário, o registro do dispositivo falhará e PoFxRegisterDeviceretornará 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.