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

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

ChangeContext

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

OperationStatus

包含 NTSTATUS 程式代碼之變數的指標。 裝置驅動程式不得變更此變數的值，除非當 ChangeContext 參數所指向之 KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT 結構 狀態 成員 KeProcessorAddStartNotify時發生錯誤。

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

[in, optional] CallbackContext

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

[in] Flags

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

KE_PROCESSOR_CHANGE_ADD_EXISTING

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

傳回值

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

言論

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

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

第二次呼叫回呼函式時，StateKE_PROCESSOR_CHANGE_NOTIFY_CONTEXT 結構的成員，ChangeContext 參數包含 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