Función KeRegisterProcessorChangeCallback (wdm.h)

La rutina KeRegisterProcessorChangeCallback registra una función de devolución de llamada con el sistema operativo para que el sistema operativo notifique al controlador cuando se agregue un nuevo procesador a la partición de hardware.

Sintaxis

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

Parámetros

[in] CallbackFunction

Puntero a una función de devolución de llamada de cambio de procesador proporcionada por el controlador a la que llamará el sistema operativo cada vez que se agregue un nuevo procesador a la partición de hardware. Una función de devolución de llamada de cambio de procesador se define de la siguiente manera:

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

CallbackContext

Contexto que se proporcionó en el parámetro CallbackContext a la rutina KeRegisterProcessorChangeCallback cuando la función de devolución de llamada se registró con el sistema operativo.

ChangeContext

Puntero a una estructura de KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT que describe el evento de notificación de cambio del procesador.

OperationStatus

Puntero a una variable que contiene un código NTSTATUS. Un controlador de dispositivo no debe cambiar el valor de esta variable, excepto si se produce un error durante el procesamiento de la función de devolución de llamada cuando el miembro State de la estructura KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT a la que apunta el parámetro ChangeContext contiene KeProcessorAddStartNotify.

Se llama a la función de devolución de llamada de cambio del procesador en IRQL = PASSIVE_LEVEL.

[in, optional] CallbackContext

Contexto proporcionado por el controlador que se pasa a la función de devolución de llamada. Este parámetro puede ser NULL.

[in] Flags

Marcas opcionales que modifican el comportamiento de la rutina KeRegisterProcessorChangeCallback . La siguiente es una marca posible:

KE_PROCESSOR_CHANGE_ADD_EXISTING

Si se establece esta marca, se llama inmediatamente a la función de devolución de llamada registrada para cada procesador activo que existe actualmente en la partición de hardware, además de llamarse cada vez que se agrega un nuevo procesador a la partición de hardware. Si no se establece esta marca, solo se llama a la función de devolución de llamada registrada cada vez que se agrega un nuevo procesador al sistema.

Valor devuelto

KeRegisterProcessorChangeCallback devuelve un identificador de registro de devolución de llamada que no es NULL si la función de devolución de llamada se registra correctamente con el sistema operativo. De lo contrario, KeRegisterProcessorChangeCallback devuelve NULL. Para obtener más información sobre este identificador, vea la siguiente sección Comentarios.

Comentarios

Un controlador de dispositivo llama a la rutina KeRegisterProcessorChangeCallback para registrar una función de devolución de llamada a la que llamará el sistema operativo cada vez que se agrega un nuevo procesador a la partición de hardware. Cuando un usuario conecta un nuevo procesador a la partición, el sistema operativo llama a las funciones de devolución de llamada registradas para reequilibrar los recursos del sistema asignados entre los procesadores de la partición.

Se llama a la función de devolución de llamada registrada dos veces cada vez que se agrega un nuevo procesador a la partición de hardware. La primera vez que se llama a la función de devolución de llamada, el miembro State de la estructura KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT a la que apunta el parámetro ChangeContext contiene KeProcessorAddStartNotify. Durante esta devolución de llamada, el controlador de dispositivo debe asignar los recursos por procesador y realizar cualquier otra tarea como preparación para que el nuevo procesador se active en la partición de hardware. Si se produce un error mientras el controlador de dispositivo procesa esta devolución de llamada que podría provocar una comprobación de errores si el sistema operativo sigue agregando el nuevo procesador a la partición de hardware, la función de devolución de llamada establece la variable a la que apunta el parámetro OperationStatus a un código NTSTATUS que describe la condición de error. Por ejemplo, si el controlador de dispositivo experimenta un error de asignación de memoria para una estructura de datos por procesador para un nuevo procesador, la función de devolución de llamada establece esta variable en STATUS_INSUFFICIENT_RESOURCES. Si la devolución de llamada se procesa correctamente, no se debe cambiar el contenido de la variable a la que apunta el parámetro OperationStatus .

La segunda vez que se llama a la función de devolución de llamada, el miembro State de la estructura KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT a la que apunta el parámetro ChangeContext contiene KeProcessorAddCompleteNotify, lo que indica que el sistema operativo ha agregado el nuevo procesador a la partición de hardware correctamente, o KeProcessorAddFailureNotify., que indica que el sistema operativo no ha agregado el nuevo procesador a la partición de hardware. Si el sistema operativo agrega correctamente el nuevo procesador a la partición de hardware, no se llama a la función de devolución de llamada la segunda vez hasta que se haya iniciado el nuevo procesador y esté disponible para la programación de subprocesos. Si el sistema operativo no ha agregado el nuevo procesador a la partición de hardware, el controlador de dispositivo debe liberar los recursos por procesador durante la segunda devolución de llamada que asignó durante la primera devolución de llamada.

Si el controlador de dispositivo especifica la marca KE_PROCESSOR_CHANGE_ADD_EXISTING en el parámetro Flags cuando llama a la rutina KeRegisterProcessorChangeCallback , la función de devolución de llamada se llama inmediatamente una vez para cada procesador activo que existe actualmente en la partición de hardware. Para estas devoluciones de llamada, el miembro State de la estructura KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT a la que apunta el parámetro ChangeContext contiene KeProcessorAddStartNotify. Durante estas devoluciones de llamada, el controlador de dispositivo debe asignar los recursos por procesador y realizar otras tareas para preparar el uso de los procesadores existentes en la partición de hardware. Si el controlador de dispositivo procesa correctamente esta devolución de llamada para todos los procesadores activos que existen actualmente en la partición de hardware, se llama inmediatamente a la función de devolución de llamada para cada procesador activo que existe actualmente en la partición de hardware. Para estas devoluciones de llamada, el miembro State de la estructura KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT a la que apunta el parámetro ChangeContext contiene KeProcessorAddCompleteNotify. KeRegisterProcessorChangeCallback vuelve una vez completadas estas devoluciones de llamada.

Si se produce un error mientras el controlador de dispositivo procesa la primera devolución de llamada para uno de los procesadores activos existentes en la partición de hardware que podría provocar una comprobación de errores si el controlador continuara cargando, la función de devolución de llamada establece la variable a la que apunta el parámetro OperationStatus en un código NTSTATUS que describe la condición de error. Por ejemplo, si el controlador de dispositivo experimenta un error de asignación de memoria para una estructura de datos por procesador para un procesador activo existente, la función de devolución de llamada establece esta variable en STATUS_INSUFFICIENT_RESOURCES. Si la devolución de llamada se procesa correctamente, no se debe cambiar el contenido de la variable a la que apunta el parámetro OperationStatus .

Si el controlador de dispositivo indica un error cuando se procesa la primera devolución de llamada de uno de los procesadores activos existentes en la partición de hardware, no se llama a la función de devolución de llamada para más de los procesadores activos existentes. En su lugar, la función de devolución de llamada se llama inmediatamente una segunda vez para cada procesador activo para el que se llamó a la devolución de llamada la primera vez, excepto el procesador activo para el que la devolución de llamada indicó el error. Para estas devoluciones de llamada, el miembro State de la estructura KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT a la que apunta el parámetro ChangeContext contiene KeProcessorAddFailureNotify.

Normalmente, un controlador de dispositivo llama a la rutina KeRegisterProcessorChangeCallback desde su rutina DriverEntry . Si la llamada a la rutina KeRegisterProcessorChangeCallback devuelve NULL, la rutina DriverEntry del controlador del dispositivo debe devolver un código NTSTATUS que describa la condición de error.

Un controlador de dispositivo puede usar el contexto que se pasa en el parámetro CallbackContext a la rutina KeRegisterProcessorChangeCallback como un lugar donde la función de devolución de llamada puede almacenar el código NTSTATUS que describe la condición de error. Después, este código NTSTATUS se puede usar como valor devuelto para la rutina DriverEntry del controlador del dispositivo.

El valor de estado devuelto por KeRegisterProcessorChangeCallback indica solo si el registro de la función de devolución de llamada se realiza correctamente o no. No indica el éxito o error de ninguna llamada a funciones de devolución de llamada que pueden producirse antes de que se devuelva KeRegisterProcessorChangeCallback .

Se debe anular el registro de una función de devolución de llamada que se ha registrado para la notificación de los cambios del procesador antes de descargar el controlador del dispositivo desde el sistema operativo. Para anular el registro de la función de devolución de llamada, el controlador de dispositivo llama a la rutina KeDeregisterProcessorChangeCallback y pasa, como parámetro de entrada a esta rutina, el identificador de registro devuelto por la llamada a la rutina KeRegisterProcessorChangeCallback .

Requisitos

Requisito	Value
Plataforma de destino	Universal
Encabezado	wdm.h (incluya Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL

Consulte también

KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT

KeDeregisterProcessorChangeCallback