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 que foi 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 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 membro State da estrutura KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT apontado pelo parâmetro ChangeContext contiver 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. Este parâmetro pode ser NULL.

[in] Flags

Sinalizadores opcionais que modificam o comportamento da rotina KeRegisterProcessorChangeCallback . 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.

Retornar valor

KeRegisterProcessorChangeCallback retornará um identificador de registro de retorno de chamada não NULL se a função de retorno de chamada for registrada com êxito no sistema operacional. Caso contrário, KeRegisterProcessorChangeCallback retornará NULL. Para obter mais informações sobre esse identificador, consulte a seção Comentários a seguir.

Comentários

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 membro State da estrutura KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT 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 apontada pelo parâmetro OperationStatus como 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 membro State da estrutura KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT apontado pelo parâmetro ChangeContext contém KeProcessorAddCompleteNotify, o 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 threads. 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 alocado durante o primeiro retorno de chamada.

Se o driver do dispositivo especificar o sinalizador KE_PROCESSOR_CHANGE_ADD_EXISTING no parâmetro Flags ao chamar a rotina 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 membro State da estrutura KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT apontado pelo parâmetro ChangeContext contém KeProcessorAddStartNotify. É durante esses retornos de chamada que o driver de 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 de 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 membro State da estrutura KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT 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 fazer com que uma verificação de bug ocorra se o driver continuar a carregar, a função de retorno de chamada define a variável apontada pelo parâmetro OperationStatus como 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 para 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 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 State da estrutura KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT apontado pelo parâmetro ChangeContext contém KeProcessorAddFailureNotify.

Um driver de dispositivo normalmente chama a rotina KeRegisterProcessorChangeCallback de dentro de sua rotina DriverEntry . Se a chamada para a rotina KeRegisterProcessorChangeCallback retornar NULL, a rotina DriverEntry do driver de dispositivo deverá retornar um código NTSTATUS que descreva a condição de erro.

Um driver de dispositivo pode usar o contexto que é passado no parâmetro CallbackContext para a rotina KeRegisterProcessorChangeCallback como um local onde 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 DriverEntry do driver de dispositivo.

O valor 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 nenhuma chamada para funções de retorno de chamada que podem ocorrer antes que KeRegisterProcessorChangeCallback retorne.

Uma função de retorno de chamada que foi registrada para notificação de alterações de processador deve ser cancelada 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 retornado pela chamada para a rotina KeRegisterProcessorChangeCallback .

Requisitos

Confira também

KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT

KeDeregisterProcessorChangeCallback