Função PoFxRegisterDevice (wdm.h)

Artigo
08/08/2023

A rotina PoFxRegisterDevice registra um dispositivo com a PoFx (estrutura de gerenciamento de energia).

Sintaxe

NTSTATUS PoFxRegisterDevice(
  [in]  PDEVICE_OBJECT Pdo,
  [in]  PPO_FX_DEVICE  Device,
  [out] POHANDLE       *Handle
);

Parâmetros

[in] Pdo

Um ponteiro para um PDO ( objeto de dispositivo físico ). Esse parâmetro aponta para uma estrutura DEVICE_OBJECT que representa o dispositivo físico que está sendo registrado. O chamador é o proprietário da política de energia do dispositivo, que normalmente é o driver de função do dispositivo.

[in] Device

Um ponteiro para uma estrutura de PO_FX_DEVICE alocada pelo chamador que contém as informações de registro do dispositivo. Essa estrutura contém ponteiros para um conjunto de rotinas de retorno de chamada implementadas pelo driver de dispositivo. A PoFx chama essas rotinas para se comunicar com o driver.

[out] Handle

Um ponteiro para um local no qual a rotina grava um identificador que representa o registro do dispositivo com PoFx. O driver do dispositivo passa esse identificador como um parâmetro de entrada para as outras rotinas PoFxXxx que ele chama. O driver deve primeiro chamar PoFxRegisterDevice para registrar o dispositivo antes que o driver chame qualquer outra rotina PoFxXxx para gerenciar o dispositivo.

Retornar valor

PoFxRegisterDevice retornará STATUS_SUCCESS se a rotina registrar com êxito o dispositivo. Os possíveis valores retornados por erro incluem os seguintes códigos de status.

Código de retorno	Descrição
STATUS_INVALID_PARAMETER	Pdo é NULL; ou a estrutura PPO_FX_DEVICE tem um número de versão inválido ou uma contagem de componentes igual a zero; ou o número de estados ociosos especificados para um componente é zero; ou a descrição de um estado ocioso é inválida.
STATUS_DEVICE_NOT_READY	O dispositivo não está pronto.
STATUS_INSUFFICIENT_RESOURCES	Recursos insuficientes estão disponíveis para concluir o registro.

Comentários

Um driver de dispositivo normalmente chama essa rotina do manipulador de solicitação IRP_MN_START_DEVICE do driver. O driver não deve chamar essa rotina antes que o dispositivo receba uma solicitação de IRP_MN_START_DEVICE . O dispositivo recebe a primeira solicitação IRP_MN_START_DEVICE quando o dispositivo está sendo iniciado pela primeira vez. O dispositivo recebe uma solicitação de IRP_MN_START_DEVICE adicional sempre que o dispositivo é reiniciado após ser interrompido para balanceamento de recursos. Uma chamada PoFxRegisterDevice para registrar um dispositivo que já está registrado é um erro fatal e causa um bug marcar. Observe que o PoFx executa uma cópia profunda das estruturas do dispositivo em sua memória.

Antes que o driver chame PoFxRegisterDevice, o dispositivo deve atender às seguintes condições:

O dispositivo (ou seja, o PDO) ainda não está registrado com PoFx.
O dispositivo está no estado de energia D0 (totalmente ativado).
O dispositivo está na condição de execução.
Cada componente no dispositivo está no estado de energia F0 (totalmente ativado).
Cada componente está na condição ativa.

Ao registrar o dispositivo com PoFx, o driver assume a responsabilidade de informar o PoFx quando um componente está sendo usado ativamente e quando o componente está ocioso. Enquanto o dispositivo está registrado, o driver deve chamar a rotina PoFxActivateComponent para obter acesso aos registros de hardware de um componente, e o driver deve chamar a rotina PoFxIdleComponent para notificar PoFx quando o driver não precisar mais de acesso ao componente.

Depois que um driver chama PoFxRegisterDevice para registrar um dispositivo com PoFx, todos os componentes no dispositivo estão totalmente ligados e na condição ativa para que o driver possa concluir a inicialização do hardware. Para iniciar o gerenciamento de energia ativo, o driver deve chamar a rotina PoFxStartDevicePowerManagement .

Por padrão, PoFxStartDevicePowerManagement alterna todos os componentes para a condição ociosa. Se o driver exigir que um componente esteja na condição ativa imediatamente após o início do gerenciamento de energia, o driver deverá ativar explicitamente o componente chamando a rotina PoFxActivateComponent e essa chamada deverá ocorrer após a chamada poFxRegisterDevice , mas antes da chamada poFxStartDevicePowerManagement .

Normalmente, o driver do KMDF (Kernel-Mode Driver Framework) para um dispositivo de componente único não chama PoFxRegisterDevice para registrar o dispositivo com PoFx. Em vez disso, esse driver recebe um identificador de registro PoFx quando o KMDF chama a função de retorno de chamada EvtDeviceWdmPostPoFxRegisterDevice do driver. Para obter mais informações, consulte Suporte a vários estados de energia funcionais para dispositivos Single-Component.

Para obter informações sobre como o driver KMDF para um dispositivo de vários componentes se registra com PoFx, consulte Suporte a vários estados de energia funcionais para dispositivos Multiple-Component.

Requisitos

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