WdfDmaEnablerCreate 関数 (wdfdmaenabler.h)

  • [アーティクル]

[KMDF にのみ適用]

WdfDmaEnablerCreate メソッドは、DMA イネーブラー オブジェクトを作成します。

構文

NTSTATUS WdfDmaEnablerCreate(
  [in]           WDFDEVICE               Device,
  [in]           PWDF_DMA_ENABLER_CONFIG Config,
  [in, optional] PWDF_OBJECT_ATTRIBUTES  Attributes,
  [out]          WDFDMAENABLER           *DmaEnablerHandle
);

パラメーター

[in] Device

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

[in] Config

WDF_DMA_ENABLER_CONFIG構造体へのポインター。 ドライバーは 、WDF_DMA_ENABLER_CONFIG_INITを呼び出して、この構造体を初期化する必要があります。

[in, optional] Attributes

新しい DMA イネーブラー オブジェクトのオブジェクト属性を指定する WDF_OBJECT_ATTRIBUTES 構造体へのポインター。 このパラメーターは省略可能であり、WDF_NO_OBJECT_ATTRIBUTESできます。

[out] DmaEnablerHandle

新しい DMA イネーブラー オブジェクトへのハンドル。

戻り値

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

リターン コード 説明
STATUS_INVALID_PARAMETER
 無効なパラメーターが検出されました。
STATUS_INSUFFICIENT_RESOURCES

新しい DMA イネーブラー オブジェクトを構築するためのメモリが不足していました。
STATUS_INFO_LENGTH_MISMATCH
 WDF_DMA_ENABLER_CONFIG構造体のサイズが正しくありません。
STATUS_NOT_SUPPORTED
 ドライバーは、Windows 8より前のオペレーティング システムで DMA バージョン 3 を要求しました。
 

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

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

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

注釈

フレームワーク ベースのドライバーは、デバイスの DMA トランザクションを作成する前に WdfDmaEnablerCreate を呼び出す必要があります。

ドライバーが WdfDmaEnablerCreate を呼び出す前に、 WdfDeviceSetAlignmentRequirement を呼び出す必要があります。

WdfDmaEnablerCreate の Device パラメーターが指定するフレームワーク デバイス オブジェクトは、常に新しい DMA イネーブラー オブジェクトの親オブジェクトになります。 ドライバーがWDF_OBJECT_ATTRIBUTES構造体の ParentObject メンバーで別の親を指定した場合、フレームワークはこの値を無視します。 フレームワークは、親オブジェクトを削除すると、DMA イネーブラー オブジェクトを削除します。

システム モード DMA プロファイルを要求する Config パラメーターを使用して呼び出されると、 WdfDmaEnablerCreate によって部分的に初期化された DMA イネーブラーが作成されます。 ドライバーは、その後 WdfDmaEnablerConfigureSystemProfile を呼び出して、基になるチャネルの DMA 設定を設定する必要があります。

DMA イネーブラー オブジェクトと WdfDmaEnablerCreate の詳細については、「 DMA トランザクションの有効化」を参照してください。

例

次のコード例は、 PLX9x5x サンプル ドライバーのものです。 次の使用例は、バッファー配置のデバイスの要件を設定し、WDF_DMA_ENABLER_CONFIG構造体を初期化し、 WdfDmaEnablerCreate を呼び出します。

//
// PLx PCI9656 DMA_TRANSFER_ELEMENTS must be 16-byte aligned.
//
WdfDeviceSetAlignmentRequirement(
                                 DevExt->WdfDevice,
                                 PCI9656_DTE_ALIGNMENT_16
                                 );

//
// Create a new DMA enabler object instance. 
// Use scatter/gather, 64-bit addresses, and duplex-type profile.
//
{
    WDF_DMA_ENABLER_CONFIG   dmaConfig;
    WDF_DMA_ENABLER_CONFIG_INIT(
                                &dmaConfig,
                                WdfDmaProfileScatterGather64Duplex,
                                DevExt->MaximumTransferLength
                                );
    status = WdfDmaEnablerCreate(
                                 DevExt->WdfDevice,
                                 &dmaConfig,
                                 WDF_NO_OBJECT_ATTRIBUTES,
                                 &DevExt->DmaEnabler
                                 );
    if (!NT_SUCCESS (status)) {
        // Cannot continue, so release device resources.
        return status;
    }
}

要件

要件 値
対象プラットフォーム ユニバーサル
最小 KMDF バージョン 1.0
Header wdfdmaenabler.h (Wdf.h を含む)
Library Wdf01000.sys (「Framework ライブラリのバージョン管理」を参照)。
IRQL PASSIVE_LEVEL
DDI コンプライアンス規則 DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

こちらもご覧ください

WDF_DMA_ENABLER_CONFIG

WDF_DMA_ENABLER_CONFIG_INIT

WDF_OBJECT_ATTRIBUTES

WdfDeviceSetAlignmentRequirement