Функция KeRegisterProcessorChangeCallback (wdm.h)

Подпрограмма 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. Драйвер устройства не должен изменять значение этой переменной, за исключением случаев, когда во время обработки функции обратного вызова возникает ошибка, когда элемент StateKE_PROCESSOR_CHANGE_NOTIFY_CONTEXT структуры, на которую указывает параметр ChangeContext , содержит KeProcessorAddStartNotify.

Функция обратного вызова изменения процессора вызывается в IRQL = PASSIVE_LEVEL.

[in, optional] CallbackContext

Предоставленный драйвером контекст, который передается в функцию обратного вызова. Этот параметр может принимать значение NULL.

[in] Flags

Необязательные флаги, которые изменяют поведение подпрограммы KeRegisterProcessorChangeCallback . Ниже приведен один из возможных флагов:

KE_PROCESSOR_CHANGE_ADD_EXISTING

Если этот флаг установлен, зарегистрированная функция обратного вызова немедленно вызывается для каждого активного процессора, который в настоящее время существует в аппаратном разделе, а также вызывается при каждом добавлении нового процессора в аппаратный раздел. Если этот флаг не задан, зарегистрированная функция обратного вызова вызывается только при каждом добавлении нового процессора в систему.

Возвращаемое значение

KeRegisterProcessorChangeCallback возвращает дескриптор регистрации обратного вызова, отличный от NULL , если функция обратного вызова успешно зарегистрирована в операционной системе. В противном случае KeRegisterProcessorChangeCallback возвращает значение NULL. Дополнительные сведения об этом дескрипторове см. в следующем разделе Примечания.

Комментарии

Драйвер устройства вызывает подпрограмму KeRegisterProcessorChangeCallback , чтобы зарегистрировать функцию обратного вызова, которая должна вызываться операционной системой при каждом добавлении нового процессора в аппаратный раздел. Когда пользователь подключает новый процессор к разделу, операционная система вызывает зарегистрированные функции обратного вызова для перераспределения системных ресурсов, выделенных между процессорами в секции.

Зарегистрированная функция обратного вызова вызывается два раза при добавлении нового процессора в аппаратный раздел. При первом вызове функции обратного вызова элемент Stateструктуры KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT , на которую указывает параметр ChangeContext , содержит KeProcessorAddStartNotify. Именно во время этого обратного вызова драйвер устройства должен выделить все ресурсы для каждого процессора и выполнить любые другие задачи для подготовки нового процессора к включению в аппаратном разделе. Если во время обработки этого обратного вызова драйвером устройства возникает ошибка, которая может привести к возникновению ошибки, если операционная система продолжает добавлять новый процессор в аппаратный раздел, функция обратного вызова задает переменную, на которую указывает параметр OperationStatus , в код NTSTATUS, описывающий условие ошибки. Например, если драйвер устройства испытывает сбой выделения памяти для структуры данных для каждого процессора для нового процессора, функция обратного вызова устанавливает для этой переменной значение STATUS_INSUFFICIENT_RESOURCES. Если обратный вызов успешно обработан, содержимое переменной, на которую указывает параметр OperationStatus , не должно изменяться.

При втором вызове функции обратного вызова элемент Stateструктуры KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT , на которую указывает параметр ChangeContext , содержит либо KeProcessorAddCompleteNotify, который указывает, что операционная система успешно добавила новый процессор в аппаратный раздел, либо KeProcessorAddFailureNotify., который указывает, что операционная система не добавила новый процессор в аппаратный раздел. Если операционная система успешно добавляет новый процессор в аппаратный раздел, функция обратного вызова не вызывается во второй раз, пока не будет запущен новый процессор и доступна для планирования потоков. Если операционная система не добавила новый процессор в аппаратный раздел, драйвер устройства должен освободить все ресурсы для каждого процессора во время второго обратного вызова, выделенного во время первого обратного вызова.

Если драйвер устройства задает флаг KE_PROCESSOR_CHANGE_ADD_EXISTING в параметре Flags при вызове процедуры KeRegisterProcessorChangeCallback , функция обратного вызова немедленно вызывается один раз для каждого активного процессора, который в настоящее время существует в аппаратном разделе. Для этих обратных вызовов элемент Stateструктуры KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT , на которую указывает параметр ChangeContext , содержит KeProcessorAddStartNotify. Именно во время этих обратных вызовов драйвер устройства должен выделить все ресурсы для каждого процессора и выполнить любые другие задачи для подготовки к использованию существующих процессоров в аппаратном разделе. Если драйвер устройства успешно обрабатывает этот обратный вызов для всех активных процессоров, которые в настоящее время существуют в аппаратном разделе, функция обратного вызова немедленно вызывается снова для каждого активного процессора, который в настоящее время существует в аппаратном разделе. Для этих обратных вызовов элемент Stateструктуры KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT , на которую указывает параметр ChangeContext , содержит KeProcessorAddCompleteNotify. KeRegisterProcessorChangeCallback возвращается после завершения этих обратных вызовов.

Если во время обработки драйвером устройства первого обратного вызова одного из существующих активных процессоров в аппаратном разделе возникает ошибка, которая может привести к возникновению ошибки, если драйвер будет продолжать загружаться, функция обратного вызова задает переменную, на которую указывает параметр OperationStatus , в код NTSTATUS, описывающий условие ошибки. Например, если драйвер устройства испытывает сбой выделения памяти для структуры данных для каждого процессора для существующего активного процессора, функция обратного вызова задает для этой переменной значение STATUS_INSUFFICIENT_RESOURCES. Если обратный вызов успешно обработан, содержимое переменной, на которую указывает параметр OperationStatus , не должно изменяться.

Если драйвер устройства указывает на ошибку при обработке первого обратного вызова одного из существующих активных процессоров в аппаратном разделе, функция обратного вызова больше не вызывается для существующих активных процессоров. Вместо этого функция обратного вызова немедленно вызывается во второй раз для каждого активного процессора, для которого обратный вызов был вызван в первый раз, за исключением активного процессора, для которого обратный вызов указал ошибку. Для этих обратных вызовов элемент Stateструктуры KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT , на которую указывает параметр ChangeContext , содержит KeProcessorAddFailureNotify.

Драйвер устройства обычно вызывает подпрограмму KeRegisterProcessorChangeCallback из процедуры DriverEntry . Если вызов подпрограммы 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