KeRegisterProcessorChangeCallback 関数 (wdm.h)

[アーティクル]
03/08/2023

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構造体の State メンバーに KeProcessorAddStartNotify が含まれている場合、コールバック関数の処理中にエラーが発生する場合を除き、デバイスドライバーは、この変数の値を変更しないでください。

プロセッサ変更コールバック関数は、IRQL = PASSIVE_LEVEL で呼び出されます。

[in, optional] CallbackContext

コールバック関数に渡されるドライバー指定のコンテキスト。このパラメーターは、NULL でもかまいません。

[in] Flags

KeRegisterProcessorChangeCallback ルーチンの動作を変更する省略可能なフラグ。次の 1 つのフラグを指定できます。

KE_PROCESSOR_CHANGE_ADD_EXISTING

このフラグが設定されている場合、新しいプロセッサがハードウェアパーティションに追加されるたびに呼び出されるだけでなく、ハードウェアパーティションに現在存在するアクティブなプロセッサごとに、登録済みのコールバック関数が直ちに呼び出されます。このフラグが設定されていない場合、登録済みのコールバック関数は、新しいプロセッサがシステムに追加されるたびに呼び出されます。

戻り値

KeRegisterProcessorChangeCallback は、コールバック関数がオペレーティングシステムに正常に登録された場合、NULL 以外のコールバック登録ハンドルを返します。それ以外の場合、 KeRegisterProcessorChangeCallback は NULL を返します。このハンドルの詳細については、次の「解説」セクションを参照してください。

注釈

デバイスドライバーは 、KeRegisterProcessorChangeCallback ルーチンを呼び出して、新しいプロセッサがハードウェアパーティションに追加されるたびにオペレーティングシステムによって呼び出されるコールバック関数を登録します。ユーザーが新しいプロセッサをパーティションにホットプラグすると、オペレーティングシステムは登録済みのコールバック関数を呼び出して、パーティション内のプロセッサ間で割り当てられたシステムリソースを再調整します。

登録済みのコールバック関数は、新しいプロセッサがハードウェアパーティションに追加されるたびに 2 回呼び出されます。コールバック関数が初めて呼び出されると、ChangeContext パラメーターによって指されるKE_PROCESSOR_CHANGE_NOTIFY_CONTEXT構造体の State メンバーに KeProcessorAddStartNotify が含まれます。このコールバック中に、デバイスドライバーはプロセッサごとのリソースを割り当て、ハードウェアパーティションで新しいプロセッサがアクティブになる準備として他のタスクを実行する必要があります。オペレーティングシステムが引き続きハードウェアパーティションに新しいプロセッサを追加する場合にバグチェックが発生する可能性があるこのコールバックをデバイスドライバーが処理しているときにエラーが発生した場合、コールバック関数は OperationStatus パラメーターによって指される変数を、エラー状態を記述する NTSTATUS コードに設定します。たとえば、デバイスドライバーが新しいプロセッサのプロセッサごとのデータ構造のメモリ割り当てエラーが発生した場合、コールバック関数は、この変数をSTATUS_INSUFFICIENT_RESOURCESに設定します。コールバックが正常に処理された場合は、 OperationStatus パラメーターによって指される変数の内容を変更しないでください。

コールバック関数が 2 回目に呼び出されると、ChangeContext パラメーターが指すKE_PROCESSOR_CHANGE_NOTIFY_CONTEXT構造体の State メンバーには、オペレーティングシステムが新しいプロセッサをハードウェアパーティションに正常に追加したことを示す KeProcessorAddCompleteNotify または KeProcessorAddFailureNotify が含まれます。は、オペレーティングシステムが新しいプロセッサをハードウェアパーティションに追加しなかったことを示します。オペレーティングシステムが新しいプロセッサをハードウェアパーティションに正常に追加した場合、コールバック関数は、新しいプロセッサが開始され、スレッドスケジュールに使用できるようになるまで、2 回目は呼び出されません。オペレーティングシステムがハードウェアパーティションに新しいプロセッサを追加しなかった場合、デバイスドライバーは、最初のコールバック中に割り当てられた 2 番目のコールバック中にプロセッサごとのリソースを解放する必要があります。

デバイスドライバーが KeRegisterProcessorChangeCallback ルーチンを呼び出すときに Flags パラメーターにKE_PROCESSOR_CHANGE_ADD_EXISTING フラグを指定した場合、コールバック関数は、ハードウェアパーティションに現在存在するアクティブなプロセッサごとに 1 回すぐに呼び出されます。これらのコールバックの場合、ChangeContext パラメーターによって指されるKE_PROCESSOR_CHANGE_NOTIFY_CONTEXT構造体の State メンバーには、KeProcessorAddStartNotify が含まれます。これらのコールバック中に、デバイスドライバーはプロセッサごとのリソースを割り当て、ハードウェアパーティション内の既存のプロセッサを使用する準備をするために他のタスクを実行する必要があります。デバイスドライバーがハードウェアパーティションに現在存在するすべてのアクティブなプロセッサに対してこのコールバックを正常に処理した場合、コールバック関数は、ハードウェアパーティションに現在存在するアクティブなプロセッサごとに直ちに再度呼び出されます。これらのコールバックの場合、ChangeContext パラメーターによって指されるKE_PROCESSOR_CHANGE_NOTIFY_CONTEXT構造体の State メンバーには、KeProcessorAddCompleteNotify が含まれます。 KeRegisterProcessorChangeCallback は、これらのコールバックの完了後にを返します。

デバイスドライバーがハードウェアパーティション内の既存のアクティブなプロセッサの 1 つについて最初のコールバックを処理するときにエラーが発生し、ドライバーの読み込みを続行した場合にバグチェックが発生する可能性がある場合、コールバック関数は OperationStatus パラメーターが指す変数を、エラー状態を記述する NTSTATUS コードに設定します。たとえば、デバイスドライバーで、既存のアクティブなプロセッサのプロセッサごとのデータ構造のメモリ割り当てエラーが発生した場合、コールバック関数は、この変数をSTATUS_INSUFFICIENT_RESOURCESに設定します。コールバックが正常に処理された場合は、 OperationStatus パラメーターによって指される変数の内容を変更しないでください。

ハードウェアパーティション内の既存のアクティブなプロセッサの 1 つの最初のコールバックが処理されるときに、デバイスドライバーがエラーを示す場合、コールバック関数は、それ以上の既存のアクティブプロセッサに対して呼び出されません。代わりに、コールバック関数は、コールバックが最初に呼び出されたアクティブなプロセッサごとに 2 回目とすぐに呼び出されます。コールバックによってエラーが示されたアクティブプロセッサは除きます。これらのコールバックの場合、ChangeContext パラメーターによって指されるKE_PROCESSOR_CHANGE_NOTIFY_CONTEXT構造体の State メンバーには、KeProcessorAddFailureNotify が含まれています。

デバイスドライバーは通常、DriverEntry ルーチン内から KeRegisterProcessorChangeCallback ルーチンを呼び出します。 KeRegisterProcessorChangeCallback ルーチンの呼び出しで NULL が返された場合、デバイスドライバーの DriverEntry ルーチンは、エラー状態を記述する NTSTATUS コードを返す必要があります。

デバイスドライバーは、コールバック関数がエラー条件を記述する NTSTATUS コードを格納できる場所として、 CallbackContext パラメーターで KeRegisterProcessorChangeCallback ルーチンに渡されるコンテキストを使用できます。この NTSTATUS コードは、デバイスドライバーの DriverEntry ルーチンの戻り値として使用できます。

KeRegisterProcessorChangeCallback によって返される状態値は、コールバック関数の登録が成功したか失敗したかのみを示します。 KeRegisterProcessorChangeCallback が返される前に発生する可能性があるコールバック関数の呼び出しの成功または失敗は示されません。

プロセッサの変更を通知するために登録されているコールバック関数は、デバイスドライバーがオペレーティングシステムからアンロードされる前に登録解除する必要があります。コールバック関数の登録を解除するために、デバイスドライバーは KeDeregisterProcessorChangeCallback ルーチンを呼び出し、このルーチンへの入力パラメーターとして、 KeRegisterProcessorChangeCallback ルーチンの呼び出しによって返された登録ハンドルを渡します。

要件

要件	値
対象プラットフォーム	ユニバーサル
Header	wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
Library	NtosKrnl.lib
[DLL]	NtosKrnl.exe
IRQL	PASSIVE_LEVEL

こちらもご覧ください

KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT

KeDeregisterProcessorChangeCallback

次の方法で共有