Função KeRegisterProcessorChangeCallback (wdm.h)
A rotina KeRegisterProcessorChangeCallback registra uma função de retorno de chamada com o sistema operacional para que o sistema operacional notifique o driver quando um novo processador for adicionado à partição de hardware.
Sintaxe
PVOID KeRegisterProcessorChangeCallback(
[in] PPROCESSOR_CALLBACK_FUNCTION CallbackFunction,
[in, optional] PVOID CallbackContext,
[in] ULONG Flags
);
Parâmetros
[in] CallbackFunction
Um ponteiro para uma função de retorno de chamada de alteração de processador fornecida pelo driver que deve ser chamada pelo sistema operacional sempre que um novo processador for adicionado à partição de hardware. Uma função de retorno de chamada de alteração do processador é definida da seguinte maneira:
VOID
ProcessorCallback(
__in PVOID CallbackContext,
__in PKE_PROCESSOR_CHANGE_NOTIFY_CONTEXT ChangeContext,
__inout PNTSTATUS OperationStatus
);
CallbackContext
O contexto fornecido no parâmetro CallbackContext para a rotina KeRegisterProcessorChangeCallback quando a função de retorno de chamada foi registrada no sistema operacional.
ChangeContext
Um ponteiro para uma estrutura de KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT que descreve o evento de notificação de alteração do processador.
OperationStatus
Um ponteiro para uma variável que contém um código NTSTATUS. Um driver de dispositivo não deve alterar o valor dessa variável, exceto se ocorrer um erro durante o processamento da função de retorno de chamada quando o State membro da estrutura de KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT que é apontado pelo parâmetro ChangeContext contém KeProcessorAddStartNotify.
A função de retorno de chamada de alteração do processador é chamada em IRQL = PASSIVE_LEVEL.
[in, optional] CallbackContext
Um contexto fornecido pelo driver que é passado para a função de retorno de chamada. Esse parâmetro pode ser NULL.
[in] Flags
Sinalizadores opcionais que modificam o comportamento da rotina KeRegisterProcessorChangeCallback do. Veja a seguir um possível sinalizador:
KE_PROCESSOR_CHANGE_ADD_EXISTING
Se esse sinalizador for definido, a função de retorno de chamada registrada será imediatamente chamada para cada processador ativo que existe atualmente na partição de hardware, além de ser chamada sempre que um novo processador é adicionado à partição de hardware. Se esse sinalizador não estiver definido, a função de retorno de chamada registrada só será chamada sempre que um novo processador for adicionado ao sistema.
Valor de retorno
keRegisterProcessorChangeCallback retornará um identificador de registro de retorno de chamada NULLnão se a função de retorno de chamada for registrada com êxito com o sistema operacional. Caso contrário, KeRegisterProcessorChangeCallback retorna NULL . Para obter mais informações sobre esse identificador, consulte a seção Comentários a seguir.
Observações
Um driver de dispositivo chama a rotina KeRegisterProcessorChangeCallback para registrar uma função de retorno de chamada que deve ser chamada pelo sistema operacional sempre que um novo processador for adicionado à partição de hardware. Quando um usuário conecta um novo processador à partição, o sistema operacional chama as funções de retorno de chamada registradas para reequilibrar os recursos do sistema alocados entre os processadores na partição.
A função de retorno de chamada registrada é chamada duas vezes sempre que um novo processador é adicionado à partição de hardware. Na primeira vez em que a função de retorno de chamada é chamada, o state membro da estrutura KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT que é apontado pelo parâmetro ChangeContext contém KeProcessorAddStartNotify. É durante esse retorno de chamada que o driver de dispositivo deve alocar todos os recursos por processador e executar quaisquer outras tarefas em preparação para que o novo processador se torne ativo na partição de hardware. Se ocorrer um erro enquanto o driver do dispositivo processa esse retorno de chamada que pode fazer com que uma verificação de bug ocorra se o sistema operacional continuar a adicionar o novo processador à partição de hardware, a função de retorno de chamada definirá a variável que é apontada pelo parâmetro OperationStatus a um código NTSTATUS que descreve a condição de erro. Por exemplo, se o driver do dispositivo apresentar uma falha de alocação de memória para uma estrutura de dados por processador para um novo processador, a função de retorno de chamada definirá essa variável como STATUS_INSUFFICIENT_RESOURCES. Se o retorno de chamada for processado com êxito, o conteúdo da variável apontada pelo parâmetro OperationStatus não deverá ser alterado.
Na segunda vez em que a função de retorno de chamada é chamada, o State membro da estrutura KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT que é apontado pelo parâmetro ChangeContext contém KeProcessorAddCompleteNotify, que indica que o sistema operacional adicionou o novo processador à partição de hardware com êxito, ou KeProcessorAddFailureNotify, que indica que o sistema operacional não adicionou o novo processador à partição de hardware. Se o sistema operacional adicionar com êxito o novo processador à partição de hardware, a função de retorno de chamada não será chamada pela segunda vez até que o novo processador seja iniciado e esteja disponível para agendamento de thread. Se o sistema operacional não tiver adicionado o novo processador à partição de hardware, o driver do dispositivo deverá liberar todos os recursos por processador durante o segundo retorno de chamada que ele alocou durante o primeiro retorno de chamada.
Se o driver do dispositivo especificar o sinalizador KE_PROCESSOR_CHANGE_ADD_EXISTING no parâmetro Flags quando ele chamar a rotina de keRegisterProcessorChangeCallback, a função de retorno de chamada será imediatamente chamada uma vez para cada processador ativo que existe atualmente na partição de hardware. Para esses retornos de chamada, o state membro da estrutura KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT que é apontado pelo parâmetro ChangeContext contém KeProcessorAddStartNotify. É durante esses retornos de chamada que o driver do dispositivo deve alocar todos os recursos por processador e executar quaisquer outras tarefas para se preparar para usar os processadores existentes na partição de hardware. Se o driver do dispositivo processar com êxito esse retorno de chamada para todos os processadores ativos que existem atualmente na partição de hardware, a função de retorno de chamada será imediatamente chamada novamente para cada processador ativo que existe atualmente na partição de hardware. Para esses retornos de chamada, o State membro da estrutura KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT que é apontado pelo parâmetro ChangeContext contém KeProcessorAddCompleteNotify. keRegisterProcessorChangeCallback retorna após a conclusão desses retornos de chamada.
Se ocorrer um erro enquanto o driver do dispositivo processa o primeiro retorno de chamada para um dos processadores ativos existentes na partição de hardware que pode causar uma verificação de bugs se o driver continuar a carregar, a função de retorno de chamada definirá a variável apontada pelo parâmetro OperationStatus para um código NTSTATUS que descreve a condição de erro. Por exemplo, se o driver do dispositivo apresentar uma falha de alocação de memória para uma estrutura de dados por processador para um processador ativo existente, a função de retorno de chamada definirá essa variável como STATUS_INSUFFICIENT_RESOURCES. Se o retorno de chamada for processado com êxito, o conteúdo da variável apontada pelo parâmetro OperationStatus não deverá ser alterado.
Se o driver do dispositivo indicar um erro quando o primeiro retorno de chamada de um dos processadores ativos existentes na partição de hardware for processado, a função de retorno de chamada não será chamada para mais nenhum dos processadores ativos existentes. Em vez disso, a função de retorno de chamada é imediatamente chamada uma segunda vez para cada processador ativo para o qual o retorno de chamada foi chamado pela primeira vez, excluindo o processador ativo para o qual o retorno de chamada indicou o erro. Para esses retornos de chamada, o membro de Estado da estrutura KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT que é apontado pelo parâmetro ChangeContext contém KeProcessorAddFailureNotify.
Um driver de dispositivo normalmente chama a rotina de KeRegisterProcessorChangeCallback de dentro de sua rotina de DriverEntry. Se a chamada à rotina KeRegisterProcessorChangeCallback retornar NULL, a rotina de DriverEntry do driver do dispositivo deverá retornar um código NTSTATUS que descreve a condição de erro.
Um driver de dispositivo pode usar o contexto passado no parâmetro CallbackContext para o keRegisterProcessorChangeCallback rotina como um local em que a função de retorno de chamada pode armazenar o código NTSTATUS que descreve a condição de erro. Esse código NTSTATUS pode ser usado como o valor retornado para a rotina de driverEntry do driver de dispositivo.
O valor de status retornado por KeRegisterProcessorChangeCallback indica apenas se o registro da função de retorno de chamada é bem-sucedido ou falha. Ele não indica o êxito ou a falha de chamadas para funções de retorno de chamada que podem ocorrer antes de keRegisterProcessorChangeCallback retorna.
Uma função de retorno de chamada que foi registrada para notificação de alterações do processador deve não ser registrada antes que o driver do dispositivo seja descarregado do sistema operacional. Para cancelar o registro da função de retorno de chamada, o driver de dispositivo chama a rotina KeDeregisterProcessorChangeCallback e passa, como um parâmetro de entrada para essa rotina, o identificador de registro que foi retornado pela chamada para a rotina de keRegisterProcessorChangeCallback.
Requisitos
| Requisito | Valor |
|---|---|
| da Plataforma de Destino | Universal |
| cabeçalho | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| biblioteca | NtosKrnl.lib |
| de DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |