KeRegisterProcessorChangeCallback 함수(wdm.h)

아티클
03/08/2023

KeRegisterProcessorChangeCallback 루틴은 운영 체제에 콜백 함수를 등록하므로 새 프로세서가 하드웨어 파티션에 추가될 때 운영 체제가 드라이버에 알립니다.

구문

PVOID KeRegisterProcessorChangeCallback(
  [in]           PPROCESSOR_CALLBACK_FUNCTION CallbackFunction,
  [in, optional] PVOID                        CallbackContext,
  [in]           ULONG                        Flags
);

매개 변수

[in] CallbackFunction

하드웨어 파티션에 새 프로세서가 추가될 때마다 운영 체제에서 호출할 드라이버 제공 프로세서 변경 콜백 함수에 대한 포인터입니다. 프로세서 변경 콜백 함수는 다음과 같이 정의됩니다.

VOID
  ProcessorCallback(
    __in PVOID CallbackContext,
    __in PKE_PROCESSOR_CHANGE_NOTIFY_CONTEXT ChangeContext,
    __inout PNTSTATUS OperationStatus
    );

CallbackContext

콜백 함수가 운영 체제에 등록되었을 때 CallbackContext 매개 변수에서 KeRegisterProcessorChangeCallback 루틴에 제공된 컨텍스트입니다.

ChangeContext

프로세서 변경 알림 이벤트를 설명하는 KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT 구조체에 대한 포인터입니다.

OperationStatus

NTSTATUS 코드를 포함하는 변수에 대한 포인터입니다. ChangeContext 매개 변수가 가리키는 KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT 구조체의 State 멤버에 KeProcessorAddStartNotify가 포함된 경우 콜백 함수를 처리하는 동안 오류가 발생하는 경우를 제외하고 디바이스 드라이버는 이 변수의 값을 변경해서는 안 됩니다.

프로세서 변경 콜백 함수는 IRQL = PASSIVE_LEVEL 호출됩니다.

[in, optional] CallbackContext

콜백 함수에 전달되는 드라이버 제공 컨텍스트입니다. 이 매개 변수는 NULL일 수 있습니다.

[in] Flags

KeRegisterProcessorChangeCallback 루틴의 동작을 수정하는 선택적 플래그입니다. 다음은 하나의 가능한 플래그입니다.

KE_PROCESSOR_CHANGE_ADD_EXISTING

이 플래그를 설정하면 하드웨어 파티션에 새 프로세서가 추가될 때마다 호출되는 것 외에도 현재 하드웨어 파티션에 있는 각 활성 프로세서에 대해 등록된 콜백 함수가 즉시 호출됩니다. 이 플래그가 설정되지 않은 경우 등록된 콜백 함수는 새 프로세서가 시스템에 추가될 때마다 호출됩니다.

반환 값

콜백 함수가 운영 체제에 성공적으로 등록된 경우 KeRegisterProcessorChangeCallback은 NULL이 아닌 콜백 등록 핸들을 반환합니다. 그렇지 않으면 KeRegisterProcessorChangeCallback 은 NULL을 반환합니다. 이 핸들에 대한 자세한 내용은 다음 주의 섹션을 참조하세요.

설명

디바이스 드라이버는 KeRegisterProcessorChangeCallback 루틴을 호출하여 새 프로세서가 하드웨어 파티션에 추가될 때마다 운영 체제에서 호출할 콜백 함수를 등록합니다. 사용자가 새 프로세서를 파티션에 핫 플러그하는 경우 운영 체제는 등록된 콜백 함수를 호출하여 파티션의 프로세서 간에 할당된 시스템 리소스의 균형을 다시 조정합니다.

등록된 콜백 함수는 하드웨어 파티션에 새 프로세서가 추가될 때마다 두 번 호출됩니다. 콜백 함수가 처음 호출될 때 ChangeContext 매개 변수가 가리키는 KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT 구조체의 State 멤버에는 KeProcessorAddStartNotify가 포함됩니다. 이 콜백 중에 디바이스 드라이버는 프로세서별 리소스를 할당하고 하드웨어 파티션에서 새 프로세서가 활성화될 수 있도록 준비하기 위해 다른 작업을 수행해야 합니다. 운영 체제가 하드웨어 파티션에 새 프로세서를 계속 추가하는 경우 디바이스 드라이버가 이 콜백을 처리하는 동안 오류가 발생하는 경우 콜백 함수는 OperationStatus 매개 변수가 가리키는 변수를 오류 조건을 설명하는 NTSTATUS 코드로 설정합니다. 예를 들어 디바이스 드라이버가 새 프로세서의 프로세서별 데이터 구조에 대한 메모리 할당 오류가 발생하는 경우 콜백 함수는 이 변수를 STATUS_INSUFFICIENT_RESOURCES 설정합니다. 콜백이 성공적으로 처리되면 OperationStatus 매개 변수가 가리키는 변수의 내용을 변경하지 않아야 합니다.

콜백 함수가 두 번째로 호출될 때 ChangeContext 매개 변수가 가리키는 KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT 구조체의 State 멤버에는 운영 체제가 하드웨어 파티션에 새 프로세서를 성공적으로 추가했음을 나타내는 KeProcessorAddCompleteNotify 또는 KeProcessorAddFailureNotify가 포함됩니다.운영 체제가 하드웨어 파티션에 새 프로세서를 추가하지 않았음을 나타냅니다. 운영 체제가 하드웨어 파티션에 새 프로세서를 성공적으로 추가하면 새 프로세서가 시작되고 스레드 예약에 사용할 수 있게 될 때까지 콜백 함수가 두 번째로 호출되지 않습니다. 운영 체제에서 하드웨어 파티션에 새 프로세서를 추가하지 않은 경우 디바이스 드라이버는 첫 번째 콜백 중에 할당된 두 번째 콜백 중에 프로세서별 리소스를 해제해야 합니다.

디바이스 드라이버가 KeRegisterProcessorChangeCallback 루틴을 호출할 때 Flags 매개 변수에서 KE_PROCESSOR_CHANGE_ADD_EXISTING 플래그를 지정하는 경우 콜백 함수는 현재 하드웨어 파티션에 있는 각 활성 프로세서에 대해 즉시 한 번 호출됩니다. 이러한 콜백의 경우 ChangeContext 매개 변수가 가리키는 KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT 구조체의 State 멤버에는 KeProcessorAddStartNotify가 포함됩니다. 이러한 콜백 중에 디바이스 드라이버는 프로세서별 리소스를 할당하고 다른 작업을 수행하여 하드웨어 파티션의 기존 프로세서 사용을 준비해야 합니다. 디바이스 드라이버가 현재 하드웨어 파티션에 있는 모든 활성 프로세서에 대해 이 콜백을 성공적으로 처리하면 현재 하드웨어 파티션에 있는 각 활성 프로세서에 대해 콜백 함수가 즉시 다시 호출됩니다. 이러한 콜백의 경우 ChangeContext 매개 변수가 가리키는 KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT 구조체의 State 멤버에는 KeProcessorAddCompleteNotify가 포함됩니다. KeRegisterProcessorChangeCallback 은 이러한 콜백이 완료된 후 를 반환합니다.

디바이스 드라이버가 하드웨어 파티션의 기존 활성 프로세서 중 하나에 대한 첫 번째 콜백을 처리하는 동안 오류가 발생하면 드라이버가 계속 로드될 때 버그 검사가 발생할 수 있습니다. 콜백 함수는 OperationStatus 매개 변수가 가리키는 변수를 오류 조건을 설명하는 NTSTATUS 코드로 설정합니다. 예를 들어 디바이스 드라이버에서 기존 활성 프로세서의 프로세서별 데이터 구조에 대한 메모리 할당 오류가 발생하는 경우 콜백 함수는 이 변수를 STATUS_INSUFFICIENT_RESOURCES 설정합니다. 콜백이 성공적으로 처리되면 OperationStatus 매개 변수가 가리키는 변수의 내용을 변경하지 않아야 합니다.

하드웨어 파티션의 기존 활성 프로세서 중 하나에 대한 첫 번째 콜백이 처리될 때 디바이스 드라이버가 오류를 나타내는 경우 콜백 함수는 더 이상 기존 활성 프로세서에 대해 호출되지 않습니다. 대신 콜백 함수는 콜백이 오류를 표시한 활성 프로세서를 제외하고 콜백이 처음 호출된 각 활성 프로세서에 대해 즉시 두 번째로 호출됩니다. 이러한 콜백의 경우 ChangeContext 매개 변수가 가리키는 KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT 구조체의 State 멤버에는 KeProcessorAddFailureNotify가 포함됩니다.

디바이스 드라이버는 일반적으로 DriverEntry 루틴 내에서 KeRegisterProcessorChangeCallback 루틴을 호출합니다. KeRegisterProcessorChangeCallback 루틴에 대한 호출이 NULL을 반환하는 경우 디바이스 드라이버의 DriverEntry 루틴은 오류 조건을 설명하는 NTSTATUS 코드를 반환해야 합니다.

디바이스 드라이버는 CallbackContext 매개 변수에서 KeRegisterProcessorChangeCallback 루틴에 전달되는 컨텍스트를 콜백 함수가 오류 조건을 설명하는 NTSTATUS 코드를 저장할 수 있는 위치로 사용할 수 있습니다. 그런 다음 이 NTSTATUS 코드를 디바이스 드라이버의 DriverEntry 루틴에 대한 반환 값으로 사용할 수 있습니다.

KeRegisterProcessorChangeCallback에서 반환된 상태 값은 콜백 함수 등록이 성공하거나 실패하는지 여부만 나타냅니다. KeRegisterProcessorChangeCallback이 반환되기 전에 발생할 수 있는 콜백 함수에 대한 호출의 성공 또는 실패를 의미하지는 않습니다.

프로세서 변경 알림에 등록된 콜백 함수는 디바이스 드라이버가 운영 체제에서 언로드되기 전에 등록을 취소해야 합니다. 콜백 함수의 등록을 취소하기 위해 디바이스 드라이버는 KeDeregisterProcessorChangeCallback 루틴을 호출하고 KeRegisterProcessorChangeCallback 루틴에 대한 호출에서 반환된 등록 핸들을 이 루틴에 대한 입력 매개 변수로 전달합니다.

요구 사항

요구 사항	값
대상 플랫폼	유니버설
헤더	wdm.h(Wdm.h, Ntddk.h, Ntifs.h 포함)
라이브러리	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL

추가 정보

KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT

KeDeregisterProcessorChangeCallback

다음을 통해 공유