PoFxRegisterDevice 함수(wdm.h)

아티클
02/27/2024

PoFxRegisterDevice 루틴은 PoFx(전원 관리 프레임워크)에 디바이스를 등록합니다.

구문

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

매개 변수

[in] Pdo

PDO(물리적 디바이스 개체)에 대한 포인터입니다. 이 매개 변수는 등록 중인 물리적 디바이스를 나타내는 DEVICE_OBJECT 구조를 가리킵니다. 호출자는 일반적으로 디바이스의 함수 드라이버인 디바이스의 전원 정책 소유자입니다.

[in] Device

디바이스에 대한 등록 정보를 포함하는 호출자가 할당한 PO_FX_DEVICE 구조체에 대한 포인터입니다. 이 구조체에는 디바이스 드라이버에서 구현하는 콜백 루틴 집합에 대한 포인터가 포함되어 있습니다. PoFx는 이러한 루틴을 호출하여 드라이버와 통신합니다.

[out] Handle

루틴이 PoFx를 사용하여 디바이스 등록을 나타내는 핸들을 작성하는 위치에 대한 포인터입니다. 디바이스 드라이버는 이 핸들을 호출하는 다른 PoFxXxx 루틴에 입력 매개 변수로 전달합니다. 드라이버가 디바이스를 전원 관리하기 위해 다른 PoFxXxx 루틴을 호출하기 전에 먼저 PoFxRegisterDevice를 호출하여 디바이스를 등록해야 합니다.

반환 값

PoFxRegisterDevice는 루틴이 디바이스를 성공적으로 등록하면 STATUS_SUCCESS 반환합니다. 가능한 오류 반환 값에는 다음 상태 코드가 포함됩니다.

반환 코드	설명
STATUS_INVALID_PARAMETER	Pdo 는 NULL입니다. 또는 PPO_FX_DEVICE 구조체에 잘못된 버전 번호 또는 구성 요소 수가 0입니다. 또는 구성 요소에 대해 지정된 유휴 상태 수가 0입니다. 또는 유휴 상태에 대한 설명이 잘못되었습니다.
STATUS_DEVICE_NOT_READY	디바이스가 준비되지 않았습니다.
STATUS_INSUFFICIENT_RESOURCES	등록을 완료하는 데 사용할 수 있는 리소스가 부족합니다.

설명

디바이스 드라이버는 일반적으로 드라이버의 IRP_MN_START_DEVICE 요청 처리기에서 이 루틴을 호출합니다. 디바이스가 IRP_MN_START_DEVICE 요청을 수신하기 전에 드라이버는 이 루틴을 호출해서는 안 됩니다. 디바이스가 처음 시작될 때 디바이스는 첫 번째 IRP_MN_START_DEVICE 요청을 받습니다. 디바이스는 리소스 분산을 위해 중지된 후 디바이스가 다시 시작될 때마다 추가 IRP_MN_START_DEVICE 요청을 받습니다. 이미 등록된 디바이스를 등록하기 위한 PoFxRegisterDevice 호출은 심각한 오류이며 버그 검사 발생합니다. PoFx는 디바이스 구조의 심층 복사를 메모리에 수행합니다.

드라이버가 PoFxRegisterDevice를 호출하기 전에 디바이스는 다음 조건을 충족해야 합니다.

디바이스(즉, PDO)가 아직 PoFx에 등록되지 않았습니다.
디바이스가 D0(완전히 켜진) 전원 상태입니다.
디바이스가 실행 중인 상태입니다.
디바이스의 모든 구성 요소는 F0(완전 켜기) 전원 상태입니다.
모든 구성 요소는 활성 상태입니다.

PoFx에 디바이스를 등록하면 드라이버는 구성 요소가 적극적으로 사용되는 경우와 구성 요소가 유휴 상태일 때 PoFx에 알리는 책임을 집니다. 디바이스가 등록되어 있는 동안 드라이버는 PoFxActivateComponent 루틴을 호출하여 구성 요소의 하드웨어 레지스터에 액세스해야 하며, 드라이버는 PoFxIdleComponent 루틴을 호출하여 드라이버가 더 이상 구성 요소에 액세스할 필요가 없을 때 PoFx에 알려야 합니다.

드라이버가 PoFxRegisterDevice 를 호출하여 PoFx에 디바이스를 등록하면 디바이스의 모든 구성 요소가 완전히 켜지고 활성 상태이므로 드라이버가 하드웨어 초기화를 완료할 수 있습니다. 활성 전원 관리를 시작하려면 드라이버가 PoFxStartDevicePowerManagement 루틴을 호출해야 합니다.

기본적으로 PoFxStartDevicePowerManagement 는 모든 구성 요소를 유휴 상태로 전환합니다. 드라이버에서 전원 관리가 시작된 직후 구성 요소가 활성 상태에 있어야 하는 경우 드라이버는 PoFxActivateComponent 루틴을 호출하여 구성 요소를 명시적으로 활성화해야 하며, 이 호출은 PoFxRegisterDevice 호출 후 PoFxStartDevicePowerManagement 호출 전에 발생해야 합니다.

일반적으로 단일 구성 요소 디바이스에 대한 KMDF(Kernel-Mode Driver Framework) 드라이버는 PoFxRegisterDevice를 호출하여 PoFx 에 디바이스를 등록하지 않습니다. 대신 KMDF가 드라이버의 EvtDeviceWdmPostPoFxRegisterDevice 콜백 함수를 호출할 때 이 드라이버는 PoFx 등록 핸들을 받습니다. 자세한 내용은 Single-Component 디바이스에 대한 여러 기능 전원 상태 지원을 참조하세요.

다중 구성 요소 디바이스의 KMDF 드라이버가 PoFx에 등록되는 방법에 대한 자세한 내용은 Multiple-Component 디바이스에 대한 여러 기능 전원 상태 지원을 참조하세요.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 8 사용하여 사용할 수 있습니다.
대상 플랫폼	유니버설
헤더	wdm.h
라이브러리	Ntoskrnl.lib
DLL	Ntoskrnl.exe
IRQL	PASSIVE_LEVEL