PO_FX_COMPONENT_IDLE_STATE_CALLBACK função de retorno de chamada (wdm.h)

Artigo
02/29/2024

A rotina de retorno de chamada ComponentIdleStateCallback notifica o driver de uma alteração pendente no estado de energia fx do componente especificado.

Sintaxe

PO_FX_COMPONENT_IDLE_STATE_CALLBACK PoFxComponentIdleStateCallback;

void PoFxComponentIdleStateCallback(
  [in] PVOID Context,
  [in] ULONG Component,
  [in] ULONG State
)
{...}

Parâmetros

[in] Context

Um ponteiro para o contexto do dispositivo. O driver do dispositivo usa esse contexto para armazenar informações sobre o estado de energia atual do dispositivo. O driver do dispositivo especificou esse ponteiro no membro DeviceContext da estrutura PO_FX_DEVICE que o driver usou para registrar o dispositivo com a PoFx (estrutura de gerenciamento de energia). Esse contexto é opaco para PoFx.

[in] Component

Especifica o número do componente. 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] State

Especifica o novo estado de energia fx para o qual o componente será alterado. Se esse parâmetro for zero, o novo estado será F0; se esse parâmetro for um, o novo estado será F1; e assim por diante.

Retornar valor

Nenhum

Comentários

Quando PoFx chama a rotina ComponentIdleStateCallback do driver, o driver pode precisar se preparar para a alteração de estado fx pendente. Depois que as preparações necessárias forem concluídas, o driver deverá chamar a rotina PoFxCompleteIdleState para notificar PoFx de que o driver concluiu sua resposta ao retorno de chamada ComponentIdleStateCallback . A chamada PoFxCompleteIdleState pode ocorrer antes ou depois que a rotina ComponentIdleStateCallback retornar.

Se o componente for alternar de F0 para um estado Fx de baixa potência no qual o dispositivo perderá o estado de hardware do componente, o driver deverá salvar o estado de hardware do componente antes que a transição para o novo estado fx ocorra. Se o componente for alternar de um estado Fx de baixa potência para F0 e o estado de hardware tiver sido salvo anteriormente, o driver deverá restaurar o estado do hardware depois que a energia for restaurada para o componente.

Para alguns dispositivos, o estado de energia de um componente pode ser controlado no hardware do dispositivo. Para esses dispositivos, o driver normalmente é responsável por alterar o estado de energia do componente. Para outros dispositivos, o estado de energia de um componente pode ser controlado por hardware externo ao dispositivo, e o driver normalmente deve contar com PoFx para configurar o estado de energia do componente.

Se o driver for responsável por configurar o estado de energia do componente, o driver deverá alterar o estado de energia em resposta ao retorno de chamada ComponentIdleStateCallback . Para uma transição de F0 para um estado Fx de baixa potência, o componente está em F0 na entrada para a rotina ComponentIdleStateCallback e o driver deve alternar o componente para o novo estado Fx antes de chamar PoFxCompleteIdleState. Para uma transição de um estado Fx de baixa potência para F0, o componente está no estado fx de baixa potência na entrada para a rotina ComponentIdleStateCallback e o driver deve alternar o componente para F0 antes de chamar PoFxCompleteIdleState.

Se o driver não for responsável por configurar o estado de energia do componente, o driver deverá assumir que o componente está sempre no estado F0 na entrada para a rotina ComponentIdleStateCallback . Para uma transição pendente de F0 para um estado Fx de baixa potência, a transição para o novo estado fx não ocorre até que o driver chame PoFxCompleteIdleState. Para uma transição de um estado Fx de baixa potência para F0, a transição para F0 ocorre antes da rotina ComponentIdleStateCallback ser chamada.

PoFx nunca chama a rotina ComponentIdleStateCallback para alternar diretamente de um estado Fx de baixa potência para outro estado fx de baixa potência. Por exemplo, PoFx pode precisar alternar um componente de um estado Fx de baixa potência para outro em resposta a uma chamada para a rotina PoFxSetComponentLatency, PoFxSetComponentResidency ou PoFxSetComponentWake . Nesse caso, PoFx primeiro chama a rotina ComponentIdleStateCallback para alternar do estado fx antigo para F0 e, em seguida, chama a rotina ComponentIdleStateCallback uma segunda vez para alternar de F0 para o novo estado fx.

Exemplos

Para definir uma rotina de retorno de chamada ComponentIdleStateCallback , primeiro você deve fornecer uma declaração de função que identifique o tipo de rotina de retorno de chamada que você está definindo. O Windows fornece um conjunto de tipos de função de retorno de chamada para drivers. Declarar uma função usando os tipos de função de retorno de chamada ajuda a Análise de Código para Drivers, SDV ( Verificador de Driver Estático ) e outras ferramentas de verificação a encontrar erros e é um requisito para gravar drivers para o sistema operacional Windows.

Por exemplo, para definir uma rotina de retorno de chamada ComponentIdleStateCallback chamada MyComponentIdleStateCallback, use o tipo PO_FX_COMPONENT_IDLE_STATE_CALLBACK conforme mostrado neste exemplo de código:

PO_FX_COMPONENT_IDLE_STATE_CALLBACK MyComponentIdleStateCallback;

Em seguida, implemente sua rotina de retorno de chamada da seguinte maneira:

_Use_decl_annotations_
VOID
  MyComponentIdleStateCallback(
    PVOID Context,
    ULONG Component,
    ULONG State
    )
  {
      // Function body
  }

O tipo de função PO_FX_COMPONENT_IDLE_STATE_CALLBACK é definido no arquivo de cabeçalho Wdm.h. Para identificar erros com mais precisão ao executar as ferramentas de análise de código, adicione a _Use_decl_annotations_ anotação à sua definição de função. A _Use_decl_annotations_ anotação garante que as anotações aplicadas ao tipo de função PO_FX_COMPONENT_IDLE_STATE_CALLBACK no arquivo de cabeçalho sejam usadas. Para obter mais informações sobre os requisitos para declarações de função, consulte Declarando funções usando tipos de função de função para drivers WDM. Para obter informações sobre _Use_decl_annotations_, consulte Anotando o comportamento da função.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Com suporte em Windows 8 e versões posteriores do Windows.
Plataforma de Destino	Área de Trabalho
Cabeçalho	wdm.h (inclua Wudfwdm.h)
IRQL	Chamado em IRQL <= DISPATCH_LEVEL.