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構造体の 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 |