Funzione KeRegisterProcessorChangeCallback (wdm.h)

La routine KeRegisterProcessorChangeCallback registra una funzione di callback con il sistema operativo in modo che il sistema operativo notificherà il driver quando viene aggiunto un nuovo processore alla partizione hardware.

Sintassi

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

Parametri

[in] CallbackFunction

Puntatore a una funzione di callback del processore fornita dal driver che deve essere chiamata dal sistema operativo ogni volta che viene aggiunto un nuovo processore alla partizione hardware. Una funzione di callback delle modifiche del processore è definita come segue:

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

CallbackContext

Contesto fornito nel parametro CallbackContext alla routine KeRegisterProcessorChangeCallback quando la funzione di callback è stata registrata con il sistema operativo.

ChangeContext

Puntatore a una struttura KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT che descrive l'evento di notifica delle modifiche del processore.

OperationStatus

Puntatore a una variabile contenente un codice NTSTATUS. Un driver di dispositivo non deve modificare il valore di questa variabile, tranne se si verifica un errore durante l'elaborazione della funzione di callback quando il membro Stato della struttura KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT a cui punta il parametro ChangeContext contiene KeProcessorAddStartNotify.

La funzione di callback delle modifiche del processore viene chiamata in IRQL = PASSIVE_LEVEL.

[in, optional] CallbackContext

Contesto fornito dal driver passato alla funzione di callback. Questo parametro può essere NULL.

[in] Flags

Flag facoltativi che modificano il comportamento della routine KeRegisterProcessorChangeCallback . Di seguito è riportato un flag possibile:

KE_PROCESSOR_CHANGE_ADD_EXISTING

Se questo flag è impostato, la funzione di callback registrata viene immediatamente chiamata per ogni processore attivo attualmente presente nella partizione hardware, oltre a essere chiamato ogni volta che viene aggiunto un nuovo processore alla partizione hardware. Se questo flag non è impostato, la funzione di callback registrata viene chiamata solo ogni volta che viene aggiunto un nuovo processore al sistema.

Valore restituito

KeRegisterProcessorChangeCallback restituisce un handle di registrazione di callback non NULL se la funzione di callback viene registrata correttamente con il sistema operativo. In caso contrario, KeRegisterProcessorChangeCallback restituisceNULL. Per altre informazioni su questo handle, vedere la sezione Osservazioni seguenti.

Commenti

Un driver di dispositivo chiama la routine KeRegisterProcessorChangeCallback per registrare una funzione di callback che deve essere chiamata dal sistema operativo ogni volta che viene aggiunto un nuovo processore alla partizione hardware. Quando un utente inserisce un nuovo processore nella partizione, il sistema operativo chiama le funzioni di callback registrate per ribilanciare le risorse di sistema allocate tra i processori nella partizione.

La funzione di callback registrata viene chiamata due volte ogni volta che viene aggiunto un nuovo processore alla partizione hardware. La prima volta che viene chiamata la funzione di callback, il membro Stato della struttura KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT a cui punta il parametro ChangeContext contiene KeProcessorAddStartNotify. È durante questo callback che il driver del dispositivo deve allocare qualsiasi risorsa per processore ed eseguire qualsiasi altra attività in preparazione per il nuovo processore per diventare attivo nella partizione hardware. Se si verifica un errore durante l'elaborazione del callback del driver del dispositivo che potrebbe causare la verifica di un bugcheck se il sistema operativo continua ad aggiungere il nuovo processore alla partizione hardware, la funzione di callback imposta la variabile a cui punta il parametro OperationStatus a un codice NTSTATUS che descrive la condizione di errore. Ad esempio, se il driver del dispositivo riscontra un errore di allocazione della memoria per una struttura di dati per ogni processore per un nuovo processore, la funzione di callback imposta questa variabile su STATUS_INSUFFICIENT_RESOURCES. Se il callback viene elaborato correttamente, il contenuto della variabile a cui fa riferimento il parametro OperationStatus non deve essere modificato.

La seconda volta che viene chiamata la funzione di callback, il membro Stato della struttura KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT a cui punta il parametro ChangeContext contiene KeProcessorAddCompleteNotify, che indica che il nuovo processore è stato aggiunto correttamente alla partizione hardware o KeProcessorAddFailureNotify, che indica che il sistema operativo non ha aggiunto il nuovo processore alla partizione hardware. Se il sistema operativo aggiunge correttamente il nuovo processore alla partizione hardware, la funzione di callback non viene chiamata la seconda volta fino all'avvio del nuovo processore ed è disponibile per la pianificazione del thread. Se il sistema operativo non ha aggiunto il nuovo processore alla partizione hardware, il driver del dispositivo dovrebbe liberare qualsiasi risorsa per processore durante il secondo callback allocato durante il primo callback.

Se il driver di dispositivo specifica il flag di KE_PROCESSOR_CHANGE_ADD_EXISTING nel parametro Flags quando chiama la routine KeRegisterProcessorChangeCallback , la funzione di callback viene immediatamente chiamata una volta per ogni processore attivo attualmente presente nella partizione hardware. Per questi callback, il membro Stato della struttura KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT a cui punta il parametro ChangeContext contiene KeProcessorAddStartNotify. È durante questi callback che il driver del dispositivo deve allocare qualsiasi risorsa per processore ed eseguire qualsiasi altra attività per preparare l'uso dei processori esistenti nella partizione hardware. Se il driver del dispositivo elabora correttamente questo callback per tutti i processori attivi attualmente presenti nella partizione hardware, la funzione di callback viene immediatamente chiamata per ogni processore attivo attualmente presente nella partizione hardware. Per questi callback, il membro Stato della struttura KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT a cui punta il parametro ChangeContext contiene KeProcessorAddCompleteNotify. KeRegisterProcessorChangeCallback restituisce dopo il completamento di questi callback.

Se si verifica un errore mentre il driver del dispositivo elabora il primo callback per uno dei processori attivi esistenti nella partizione hardware che potrebbe causare un controllo di bug se il driver dovesse continuare a caricare, la funzione di callback imposta la variabile puntata dal parametro OperationStatus a un codice NTSTATUS che descrive la condizione di errore. Ad esempio, se il driver del dispositivo riscontra un errore di allocazione di memoria per una struttura di dati per ogni processore per un processore attivo esistente, la funzione di callback imposta questa variabile su STATUS_INSUFFICIENT_RESOURCES. Se il callback viene elaborato correttamente, il contenuto della variabile a cui fa riferimento il parametro OperationStatus non deve essere modificato.

Se il driver di dispositivo indica un errore quando viene elaborato il primo callback per uno dei processori attivi esistenti nella partizione hardware, la funzione di callback non viene chiamata per altri processori attivi esistenti. La funzione di callback viene invece chiamata immediatamente una seconda volta per ogni processore attivo per cui il callback è stato chiamato la prima volta, escluso il processore attivo per cui il callback ha indicato l'errore. Per questi callback, il membro Stato della struttura KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT a cui punta il parametro ChangeContext contiene KeProcessorAddFailureNotify.

Un driver di dispositivo chiama in genere la routine KeRegisterProcessorChangeCallback dall'interno della routine DriverEntry . Se la chiamata alla routine KeRegisterProcessorChangeCallback restituisceNULL, la routine DriverEntry del driver del dispositivo deve restituire un codice NTSTATUS che descrive la condizione di errore.

Un driver di dispositivo può usare il contesto passato nel parametro CallbackContext alla routine KeRegisterProcessorChangeCallback come luogo in cui la funzione di callback può archiviare il codice NTSTATUS che descrive la condizione di errore. Questo codice NTSTATUS può quindi essere usato come valore restituito per la routine DriverEntry del driver del dispositivo.

Il valore di stato restituito da KeRegisterProcessorChangeCallback indica solo se la registrazione della funzione di callback ha esito positivo o negativo. Non indica l'esito positivo o negativo di qualsiasi chiamata a funzioni di callback che potrebbero verificarsi prima che KeRegisterProcessorChangeCallback restituisca .

Una funzione di callback registrata per la notifica delle modifiche del processore deve essere annullata prima che il driver del dispositivo venga scaricato dal sistema operativo. Per annullare la registrazione della funzione di callback, il driver del dispositivo chiama la routine KeDeregisterProcessorChangeCallback e passa, come parametro di input a questa routine, l'handle di registrazione restituito dalla chiamata alla routine KeRegisterProcessorChangeCallback .

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Intestazione	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL

Vedi anche

KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT

KeDeregisterProcessorChangeCallback