WdfInterruptCreate 関数 (wdfinterrupt.h)

  • [アーティクル]

[KMDF と UMDF に適用]

WdfInterruptCreate メソッドは、フレームワーク割り込みオブジェクトを作成します。

構文

NTSTATUS WdfInterruptCreate(
  [in]           WDFDEVICE              Device,
  [in]           PWDF_INTERRUPT_CONFIG  Configuration,
  [in, optional] PWDF_OBJECT_ATTRIBUTES Attributes,
  [out]          WDFINTERRUPT           *Interrupt
);

パラメーター

[in] Device

フレームワーク デバイス オブジェクトへのハンドル。

[in] Configuration

WDF_INTERRUPT_CONFIG_INITの呼び出しによって初期化されたWDF_INTERRUPT_CONFIG構造体へのポインター。

[in, optional] Attributes

フレームワーク割り込みオブジェクトのオブジェクト属性を指定する WDF_OBJECT_ATTRIBUTES 構造体へのポインター。 (詳細については、「解説」を参照してください)。このパラメーターは省略可能であり、WDF_NO_OBJECT_ATTRIBUTESできます。

[out] Interrupt

新しい割り込みオブジェクトへのハンドルを受け取る場所へのポインター。

戻り値

操作が成功した場合、WdfInterruptCreate はSTATUS_SUCCESSを返します。 それ以外の場合、このメソッドは次のいずれかの値を返す可能性があります。

リターン コード 説明
STATUS_INFO_LENGTH_MISMATCH
 WDF_INTERRUPT_CONFIG構造体のサイズが正しくありません。
STATUS_INVALID_PARAMETER
 無効なパラメーターが指定されました。
STATUS_INVALID_DEVICE_STATE

デバイスの起動後に WdfInterruptCreate が呼び出されました。

また、ドライバーのEVT_WDF_DEVICE_PREPARE_HARDWAREコールバック ルーチンが WdfInterruptCreate を呼び出し、WDF_INTERRUPT_CONFIG構造体の InterruptRaw メンバーと InterruptTranslated メンバーを NULL に設定した場合、WdfInterruptCreate もこの値を返します。
STATUS_INSUFFICIENT_RESOURCES
 メモリが不足していました。
STATUS_WDF_PARENT_ASSIGNMENT_NOT_ALLOWED
 KMDF バージョン 1.9 以前では、ドライバーは、WDF_OBJECT_ATTRIBUTES構造体の ParentObject メンバーに NULL 以外の値を指定しました。

KMDF バージョン 1.11 以降では、ドライバーは、WDF_OBJECT_ATTRIBUTES構造体の ParentObject メンバーのフレームワーク デバイスまたはキュー以外の値を指定しました。
STATUS_WDF_INCOMPATIBLE_EXECUTION_LEVEL
 WDF_INTERRUPT_CONFIG構造体の AutomaticSerialization メンバーは TRUE に設定され、次のいずれかになります。
  • 割り込みの親オブジェクトの実行レベルは WdfExecutionLevelPassive で、ドライバーは EvtInterruptDpc を提供しています。
  • 割り込みの親オブジェクトの実行レベルは WdfExecutionLevelDispatch であり、ドライバーは EvtInterruptWorkItem を提供しています。
詳細については、「 WDF_INTERRUPT_CONFIG」を参照してください。
STATUS_NOT_SUPPORTED
 ドライバーは、Windows 8より前のプラットフォームでパッシブ レベルの割り込み処理を要求しました。
 

WdfInterruptCreate メソッドが返す可能性があるその他の戻り値の一覧については、「フレームワーク オブジェクト作成エラー」を参照してください。

このメソッドは、他の NTSTATUS 値を返す場合もあります。

ドライバーが無効なオブジェクト ハンドルを提供すると、バグ チェックが発生します。

注釈

ドライバーは通常、EvtDriverDeviceAdd コールバック関数から WdfInterruptCreate メソッドを呼び出します。 KMDF バージョン 1.11 および UMDF バージョン 2.0 以降では、ドライバーは EvtDevicePrepareHardware から WdfInterruptCreate を呼び出すことができます。 ドライバーが EvtDriverDeviceAdd から WdfInterruptCreate を呼び出す場合、WDF_INTERRUPT_CONFIG構造体の InterruptRaw メンバーと InterruptTranslated メンバーは NULL である必要があります。 ドライバーが WdfInterruptCreateを EvtDevicePrepareHardware から呼び出す場合、これらのメンバーは両方とも有効である必要があります。

ウェイク対応割り込みオブジェクトを作成する場合は、「デバイスのスリープ解除に割り込みを使用する」の説明に従って、EvtDevicePrepareHardware から WdfInterruptCreate を呼び出す必要があります。

ドライバーは、デバイスに必要な割り込みベクトルごとに WdfInterruptCreate を 1 回呼び出す必要があります。 デバイスがメッセージシグナル割り込み (MSI) をサポートしている場合、ドライバーは、デバイスがサポートできるメッセージごとに割り込みオブジェクトを作成する必要があります。

PnP マネージャーがシステム リソースをデバイスに割り当てると、フレームワークは、ドライバーが作成した割り込みオブジェクトに、デバイスに割り当てられた割り込みリソースに関する情報を格納します。 (プラグ アンド プレイをサポートしていないドライバーは、割り込みオブジェクトを使用できません。

システムは、デバイスがサポートできる割り込みリソースの一部を割り当てない場合があります。 たとえば、ドライバーは、8 つの MSI メッセージをサポートできるデバイスの 8 つの割り込みオブジェクトを作成します。 ただし、システムによってデバイスに割り当てられるメッセージは 1 つだけです。 その場合、割り込みオブジェクトのうち 7 個は使用されません。

通常、ドライバーは割り込みオブジェクトの コンテキスト空間に、デバイス割り込みレジスタのコピーされた内容などの割り込み固有の情報を格納する必要があります。 ドライバーが WdfInterruptCreate に渡すWDF_OBJECT_ATTRIBUTES構造体は、コンテキスト空間を記述する必要があります。

フレームワーク バージョン 1.9 以前を使用するドライバーの場合、各割り込みオブジェクトの親は割り込みが属するデバイス オブジェクトです。 ドライバーはこの親を変更できません。また、WDF_OBJECT_ATTRIBUTES構造体の ParentObject メンバーは NULL である必要があります。 バージョン 1.11 以降では、 ParentObject には フレームワーク デバイス オブジェクトまたはキュー オブジェクトを指定できます。 ドライバーが親を指定する場合、ドライバーは、構成構造体の AutomaticSerialization メンバーを TRUE に設定する必要があります。 ドライバーは、DIRQL での割り込みと パッシブ レベルの割り込みの両方の親を指定できます。

ドライバーがフレームワーク割り込みオブジェクト の EvtCleanupCallback または EvtDestroyCallback コールバック関数を提供する場合、フレームワークは IRQL = PASSIVE_LEVEL でこれらのコールバック関数を呼び出します。

フレームワーク ベースのドライバーでの割り込みの処理の詳細については、「 ハードウェア割り込みの処理」を参照してください。

例

次のコード例では、 WDF_INTERRUPT_CONFIG 構造体とWDF_OBJECT_ATTRIBUTES構造体を初期化し、 WdfInterruptCreate を呼び出します。

NTSTATUS  status;
WDF_INTERRUPT_CONFIG  interruptConfig;
WDF_OBJECT_ATTRIBUTES  interruptAttributes;

WDF_INTERRUPT_CONFIG_INIT(
                          &interruptConfig,
                          MyEvtInterruptIsr,
                          MyEvtInterruptDpc
                          );
WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(
                                        &interruptAttributes,
                                        INTERRUPT_DATA
                                        );
status = WdfInterruptCreate(
                            device,
                            &interruptConfig,
                            &interruptAttributes,
                            &devExt->WdfInterrupt
                            );

要件

要件 値
対象プラットフォーム ユニバーサル
最小 KMDF バージョン 1.0
最小 UMDF バージョン 2.0
Header wdfinterrupt.h (Wdf.h を含む)
Library Wdf01000.sys (KMDF);WUDFx02000.dll (UMDF)
IRQL <=DISPATCH_LEVEL
DDI コンプライアンス規則 DriverCreate(kmdf)、 KmdfIrql(kmdf)、 KmdfIrql2(kmdf)、KmdfIrqlExplicit(kmdf)

こちらもご覧ください

EvtDriverDeviceAdd

WDF_INTERRUPT_CONFIG

WDF_INTERRUPT_CONFIG_INIT

WDF_OBJECT_ATTRIBUTES

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE