Função PoFxRegisterComponentPerfStates (wdm.h)

  • Artigo

A rotina PoFxRegisterComponentPerfStates registra um componente de dispositivo para gerenciamento de estado de desempenho pela PoFx (estrutura de gerenciamento de energia).

Sintaxe

NTSTATUS PoFxRegisterComponentPerfStates(
  [in]  POHANDLE                             Handle,
  [in]  ULONG                                Component,
  [in]  ULONGLONG                            Flags,
  [in]  PPO_FX_COMPONENT_PERF_STATE_CALLBACK ComponentPerfStateCallback,
  [in]  PPO_FX_COMPONENT_PERF_INFO           InputStateInfo,
  [out] PPO_FX_COMPONENT_PERF_INFO           *OutputStateInfo
);

Parâmetros

[in] Handle

Um identificador que representa o registro do dispositivo com PoFx. O driver do dispositivo recebeu esse identificador anteriormente da rotina PoFxRegisterDevice .

[in] Component

O índice que identifica o componente cujos estados de desempenho serão gerenciados. Esse parâmetro é um índice na matriz Components na estrutura PO_FX_DEVICE que o driver de dispositivo usou para registrar o dispositivo com PoFx. Se a matriz Componentes contiver N elementos, os índices de componentes variam de 0 a N-1.

[in] Flags

Os sinalizadores que modificam o comportamento do registro de estado de desempenho. Defina esse membro como zero ou como um dos seguintes sinalizadores PO_FX_FLAG_PERF_ bitsXXX :

Valor Significado
PO_FX_FLAG_PERF_PEP_OPTIONAL
0x1
 Indica que o driver pode alterar os estados de desempenho sem assistência do PEP (plug-in de extensão de plataforma) ou que o driver está registrando estados de desempenho com PoFx apenas para fins de registro em log. Se esse sinalizador for definido, a chamada PoFxRegisterComponentPerfStates ainda terá êxito se o PEP não der suporte a estados de desempenho para o componente.
PO_FX_FLAG_PERF_QUERY_ON_F0
0x2
 Para alguns dispositivos, o PEP pode precisar colocar um estado de desempenho definido para um componente em um determinado estado de desempenho (conhecido como estado de desempenho nominal) quando ocioso o componente. Os drivers definem esse sinalizador se o componente contiver estados de desempenho nominais, nesse caso, PoFx consultará o PEP para determinar o estado de desempenho atual quando o componente fizer a transição para F0.
PO_FX_FLAG_PERF_QUERY_ON_ALL_IDLE_STATES
0x4
 Para alguns dispositivos, o PEP pode precisar colocar um estado de desempenho definido para um componente em um determinado estado de desempenho (conhecido como estado de desempenho nominal) quando ele faz a transição do componente entre estados ociosos. Os drivers definem esse sinalizador se esse componente contiver estados de desempenho nominais, nesse caso, o PoFx consultará o PEP para determinar o estado de desempenho atual quando o componente fizer a transição entre estados ociosos.

[in] ComponentPerfStateCallback

Um ponteiro para uma rotina ComponentPerfStateCallback . Essa rotina é chamada quando PoFx conclui o registro em log e notifica o PEP sobre uma transição de estado de desempenho iniciada pela chamada do driver para PoFxIssueComponentPerfStateChange ou PoFxIssueComponentPerfStateChangeMultiple. Esse retorno de chamada pode ser o mesmo para todos os componentes e todos os dispositivos; O PoFx fornece o identificador do dispositivo e o índice do componente em cada chamada de conclusão.

[in] InputStateInfo

Se o driver fornecer informações de estado de desempenho, esse parâmetro conterá um ponteiro para um driver alocado PO_FX_COMPONENT_PERF_INFO estrutura que fornece informações de estado de desempenho para PoFx. Se o driver exigir informações de estado de desempenho do PEP, esse parâmetro deverá ser definido como NULL.

[out] OutputStateInfo

Se o driver exigir informações de estado de desempenho do PEP, após um registro bem-sucedido, esse parâmetro conterá um ponteiro para uma estrutura PO_FX_COMPONENT_PERF_INFO que fornece informações de estado de desempenho definidas pelo PEP. Se o driver fornecer informações de estado de desempenho, esse parâmetro deverá ser definido como NULL.

A memória alocada para esse parâmetro é gerenciada pelo PoFx e o driver não deve liberar essa memória quando o dispositivo for removido. O tempo de vida dessa memória é garantido para exceder o tempo de vida do componente PoFx que contém esses conjuntos de estado de desempenho.

Retornar valor

PoFxRegisterComponentPerfStates retornará STATUS_SUCCESS se PoFx aceitar o registro de estados de desempenho do dispositivo. Se qualquer uma das informações necessárias não for fornecida ou incorreta, o registro falhará com um código de retorno diferente de STATUS_SUCCESS. Os valores de retorno de erro possíveis incluem os seguintes códigos de status.

Código de retorno Descrição
STATUS_NOT_IMPLEMENTED
 O parâmetro Flags não inclui o sinalizador PO_FX_FLAG_PERF_PEP_OPTIONAL e o PEP não é capaz de fornecer gerenciamento de estado de desempenho para este dispositivo.
STATUS_INVALID_PARAMETER
 Tanto InputStateInfo quanto OutputStateInfo são NULL ou ambos os parâmetros não são NULL ou não há conjuntos de estado de desempenho na estrutura PO_FX_COMPONENT_PERF_INFO que foi atribuída ao parâmetro InputStateInfo .

Comentários

Observe que o PoFx executa uma cópia profunda das estruturas do dispositivo em sua memória.

O driver ou o PEP (plug-in de extensão de plataforma) podem fornecer informações sobre os estados de desempenho compatíveis com cada componente:

  • Se o driver fornecer informações de estado de desempenho, o driver deverá definir o parâmetro InputStateInfo como um ponteiro para uma estrutura PO_FX_COMPONENT_PERF_INFO que contenha as informações de estado de desempenho. Caso contrário, o driver deve definir esse parâmetro como NULL.
  • Se o PEP fornecer informações de estado de desempenho, o driver deverá definir o parâmetro OutputStateInfo como um ponteiro válido para uma estrutura PO_FX_COMPONENT_PERF_INFO que recebe as informações de estado de desempenho. Caso contrário, o driver deve definir esse parâmetro como NULL.
Se o PEP não der suporte a estados de desempenho, o driver poderá registrar-se para suporte de estado de desempenho com PoFx somente para fins de registro em log.

Se o driver se registrar para suporte de estado de desempenho somente para fins de registro em log ou se o driver puder funcionar corretamente com ou sem suporte pep para o gerenciamento de estado de desempenho, o driver deverá definir o sinalizador PO_FX_FLAG_PERF_PEP_OPTIONAL no parâmetro Flags . Se o sinalizador estiver definido, a chamada de registro terá êxito mesmo se o PEP não fornecer suporte para estados de desempenho.

Se o driver exigir que o PEP forneça informações de estado de desempenho, o driver não poderá definir o sinalizador PO_FX_FLAG_PERF_PEP_OPTIONAL no parâmetro Flags .

Requisitos

Requisito Valor
Cliente mínimo com suporte Disponível a partir do Windows 10.
Plataforma de Destino Universal
Cabeçalho wdm.h
Biblioteca Ntoskrnl.lib
DLL Ntoskrnl.exe
IRQL <= APC_LEVEL

Confira também

ComponentPerfStateCallback

Gerenciamento de Estado de Desempenho do Dispositivo

PO_FX_COMPONENT_PERF_INFO

PoFxRegisterDevice