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

當回呼函式向操作系統註冊回呼函式時，在 KeRegisterProcessorChangeCallback 例程中提供給 KeRegisterProcessorChangeCallback 參數中的內容。

ChangeContext

描述處理器變更通知事件的 KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT 結構的指標。

OperationStatus

包含 NTSTATUS 程式代碼之變數的指標。 當 ChangeContext 參數所指向之 KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT 結構的 State 成員包含 KeProcessorAddStartNotify 時，設備驅動器不得變更此變數的值，除非在回呼函式處理期間發生錯誤。

處理器變更回呼函式是在 IRQL = PASSIVE_LEVEL呼叫。

[in, optional] CallbackContext

傳遞至回調函式的驅動程式提供內容。 此參數可以是 Null。

[in] Flags

修改 KeRegisterProcessorChangeCallback 例程行為的選擇性旗標。 以下是其中一個可能旗標：

KE_PROCESSOR_CHANGE_ADD_EXISTING

如果設定此旗標，除了每次將新的處理器新增至硬體分割區時，還會立即針對目前存在於硬體分割區中的每個使用中處理器呼叫已註冊的回呼函式。 如果未設定此旗標，則只有在將新的處理器新增至系統時，才會呼叫已註冊的回呼函式。

傳回值

如果回呼函式已成功向操作系統註冊，KeRegisterProcessorChangeCallback 會傳回非 NULL 回呼註冊句柄。 否則， KeRegisterProcessorChangeCallback 會傳回 NULL。 如需此句柄的詳細資訊，請參閱下列一節。

備註

設備驅動器會呼叫 KeRegisterProcessorChangeCallback 例程，以註冊每當新的處理器新增至硬體磁碟分區時，操作系統要呼叫的回呼函式。 當使用者將新的處理器插入分割區時，操作系統會呼叫已註冊的回呼函式，以重新平衡分割區中處理器之間配置的系統資源。

每當將新的處理器新增至硬體分割區時，就會呼叫已註冊的回呼函式兩次。 第一次呼叫回呼函式時，ChangeContext 參數所指向之KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT結構的 State 成員包含 KeProcessorAddStartNotify。 在此回呼期間，設備驅動器應該配置任何每個處理器資源，並執行任何其他工作，以準備新處理器在硬體分割區中變成作用中。 如果設備驅動器處理此回呼時發生錯誤，如果操作系統繼續將新的處理器新增至硬體磁碟分區，則回呼函式會將 OperationStatus 參數所指向的變數設定為描述錯誤狀況的 NTSTATUS 程式代碼。 例如，如果設備驅動器針對新處理器的每個處理器數據結構遇到記憶體配置失敗，回呼函式會將此變數設定為STATUS_INSUFFICIENT_RESOURCES。 如果成功處理回呼， 則不應變更 OperationStatus 參數所指向之變數的內容。

第二次呼叫回呼函式時，ChangeContext 參數所指向之KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT結構的 State 成員包含 KeProcessorAddCompleteNotify，這表示操作系統已成功將新的處理器新增至硬體分割區，或 KeProcessorAddFailureNotify，表示操作系統未將新的處理器新增至硬體磁碟分區。 如果操作系統成功將新的處理器新增至硬體磁碟分區，則回呼函式不會第二次呼叫，直到新的處理器啟動且可供線程排程使用為止。 如果操作系統未將新的處理器新增至硬體磁碟分區，則設備驅動器應該在第一次回呼期間配置的第二個回呼期間釋放任何每個處理器資源。

如果設備驅動器在呼叫 KeRegisterProcessorChangeCallback 例程時，在 Flags 參數中指定KE_PROCESSOR_CHANGE_ADD_EXISTING旗標，則會針對目前存在於硬體分割區中的每個使用中處理器，立即呼叫回呼函式一次。 針對這些回呼，ChangeContext 參數所指向之KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT結構的 State 成員包含 KeProcessorAddStartNotify。 在回呼期間，設備驅動器應該配置任何每個處理器資源，並執行任何其他工作來準備使用硬體分割區中的現有處理器。 如果設備驅動器已成功處理目前存在於硬體磁碟分區中之所有作用中處理器的回呼，則會針對目前存在於硬體磁碟分區中的每個作用中處理器，立即呼叫回呼函式。 針對這些回呼，ChangeContext 參數所指向之 KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT 結構的 State 成員包含 KeProcessorAddCompleteNotify。 KeRegisterProcessorChangeCallback 會在這些回呼完成之後傳回。

如果在設備驅動器處理硬體磁碟分區中其中一個現有作用中處理器的第一個回呼時發生錯誤，如果驅動程式繼續載入，則回呼函式會將OperationStatus 參數指向的變數設定為描述錯誤狀況的 NTSTATUS 程式代碼。 例如，如果設備驅動器在現有使用中處理器的每個處理器數據結構遇到記憶體配置失敗，回呼函式會將此變數設定為STATUS_INSUFFICIENT_RESOURCES。 如果成功處理回呼， 則不應變更 OperationStatus 參數所指向之變數的內容。

如果設備驅動器指出在處理硬體分割區中其中一個現有作用中處理器的第一次回呼時發生錯誤，則不會針對任何其他現有的使用中處理器呼叫回呼函式。 相反地，回呼函式會針對第一次呼叫回呼的每個使用中處理器立即呼叫一次，但不包括回呼指出錯誤的使用中處理器。 針對這些回呼，ChangeContext 參數所指向之KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT結構的 State 成員包含 KeProcessorAddFailureNotify。

設備驅動器通常會從其 DriverEntry 例程內呼叫 KeRegisterProcessorChangeCallback 例程。 如果 呼叫 KeRegisterProcessorChangeCallback 例程傳回 NULL，則設備驅動器的 DriverEntry 例程應該會傳回描述錯誤狀況的 NTSTATUS 程式代碼。

設備驅動器可以使用 CallbackContext 參數中傳遞至 KeRegisterProcessorChangeCallback 例程的內容，作為回呼函式可以儲存 NTSTATUS 程式代碼描述錯誤狀況的位置。 然後，此 NTSTATUS 程式代碼可作為設備驅動器 DriverEntry 例程的傳回值。

KeRegisterProcessorChangeCallback 所傳回的狀態值只會指出回呼函式的註冊成功或失敗。 它不會指出 對 KeRegisterProcessorChangeCallback 傳回之前可能發生之回呼函式的任何呼叫成功或失敗。

在從操作系統卸除設備驅動器之前，必須先取消註冊已註冊處理器變更通知的回呼函式。 若要取消註冊回呼函式，設備驅動器會呼叫 KeDeregisterProcessorChangeCallback 例程，並將此例程的輸入參數傳遞給此例程，這是 KeRegisterProcessorChangeCallback 例程呼叫所傳回的註冊句柄。

規格需求

另請參閱

KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT

KeDeregisterProcessorChangeCallback