Función PoFxRegisterDevice (wdm.h)

Artículo
08/08/2023

La rutina PoFxRegisterDevice registra un dispositivo con el marco de administración de energía (PoFx).

Sintaxis

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

Parámetros

[in] Pdo

Puntero a un objeto de dispositivo físico (PDO). Este parámetro apunta a una estructura de DEVICE_OBJECT que representa el dispositivo físico que se está registrando. El autor de la llamada es el propietario de la directiva de energía del dispositivo, que suele ser el controlador de funciones del dispositivo.

[in] Device

Puntero a una estructura de PO_FX_DEVICE asignada por el autor de la llamada que contiene la información de registro del dispositivo. Esta estructura contiene punteros a un conjunto de rutinas de devolución de llamada implementadas por el controlador de dispositivo. PoFx llama a estas rutinas para comunicarse con el controlador.

[out] Handle

Puntero a una ubicación en la que la rutina escribe un identificador que representa el registro del dispositivo con PoFx. El controlador de dispositivo pasa este identificador como parámetro de entrada a las demás rutinas PoFxXxx a las que llama. El controlador debe llamar primero a PoFxRegisterDevice para registrar el dispositivo antes de que el controlador llame a cualquier otra rutina PoFxXxx para administrar el dispositivo.

Valor devuelto

PoFxRegisterDevice devuelve STATUS_SUCCESS si la rutina registra correctamente el dispositivo. Entre los posibles valores devueltos de error se incluyen los siguientes códigos de estado.

Código devuelto	Descripción
STATUS_INVALID_PARAMETER	Pdo es NULL; o la estructura PPO_FX_DEVICE tiene un número de versión no válido o un recuento de componentes de cero; o el número de estados inactivos especificados para un componente es cero; o la descripción de un estado inactivo no es válida.
STATUS_DEVICE_NOT_READY	El dispositivo no está listo.
STATUS_INSUFFICIENT_RESOURCES	Hay recursos insuficientes disponibles para completar el registro.

Comentarios

Normalmente, un controlador de dispositivo llama a esta rutina desde el controlador IRP_MN_START_DEVICE controlador de solicitudes. El controlador no debe llamar a esta rutina antes de que el dispositivo reciba una solicitud de IRP_MN_START_DEVICE . El dispositivo recibe la primera solicitud IRP_MN_START_DEVICE cuando el dispositivo se inicia por primera vez. El dispositivo recibe una solicitud de IRP_MN_START_DEVICE adicional cada vez que se reinicia el dispositivo después de detenerse para el equilibrio de recursos. Una llamada a PoFxRegisterDevice para registrar un dispositivo que ya está registrado es un error irrecuperable y provoca una comprobación de errores. Tenga en cuenta que PoFx realiza una copia profunda de las estructuras del dispositivo en su memoria.

Antes de que el controlador llame a PoFxRegisterDevice, el dispositivo debe cumplir las condiciones siguientes:

El dispositivo (es decir, el PDO) aún no está registrado con PoFx.
El dispositivo está en estado de alimentación D0 (totalmente encendido).
El dispositivo está en la condición en ejecución.
Todos los componentes del dispositivo están en estado de alimentación F0 (totalmente encendido).
Cada componente está en la condición activa.

Al registrar el dispositivo con PoFx, el controlador asume la responsabilidad de informar a PoFx cuando se usa activamente un componente y cuando el componente está inactivo. Mientras el dispositivo está registrado, el controlador debe llamar a la rutina PoFxActivateComponent para obtener acceso a los registros de hardware de un componente y el controlador debe llamar a la rutina PoFxIdleComponent para notificar a PoFx cuando el controlador ya no requiere acceso al componente.

Después de que un controlador llame a PoFxRegisterDevice para registrar un dispositivo con PoFx, todos los componentes del dispositivo están totalmente activados y en la condición activa para que el controlador pueda terminar de inicializar el hardware. Para iniciar la administración de energía activa, el controlador debe llamar a la rutina PoFxStartDevicePowerManagement .

De forma predeterminada, PoFxStartDevicePowerManagement cambia todos los componentes a la condición inactiva. Si el controlador requiere que un componente esté en la condición activa inmediatamente después de que se inicie la administración de energía, el controlador debe activar explícitamente el componente llamando a la rutina PoFxActivateComponent y esta llamada debe producirse después de la llamada a PoFxRegisterDevice , pero antes de la llamada a PoFxStartDevicePowerManagement .

Normalmente, el controlador de Kernel-Mode Driver Framework (KMDF) para un dispositivo de un solo componente no llama a PoFxRegisterDevice para registrar el dispositivo con PoFx. En su lugar, este controlador recibe un identificador de registro de PoFx cuando KMDF llama a la función de devolución de llamada EvtDeviceWdmPostPoFxRegisterDevice del controlador. Para obtener más información, consulte Compatibilidad con varios estados de energía funcionales para dispositivos Single-Component.

Para obtener información sobre cómo se registra el controlador KMDF para un dispositivo de varios componentes con PoFx, consulte Compatibilidad con varios estados de energía funcional para Multiple-Component dispositivos.

Requisitos

Requisito	Value
Cliente mínimo compatible	Disponible a partir de Windows 8.
Plataforma de destino	Universal
Encabezado	wdm.h
Library	Ntoskrnl.lib
Archivo DLL	Ntoskrnl.exe
IRQL	PASSIVE_LEVEL