WdfCommonBufferCreate 関数 (wdfcommonbuffer.h)

  • [アーティクル]

[KMDF にのみ適用]

WdfCommonBufferCreate メソッドは、ドライバーとダイレクト メモリ アクセス (DMA) デバイスの両方が同時にアクセスできるメモリ バッファーを作成します。

構文

NTSTATUS WdfCommonBufferCreate(
  [in]           WDFDMAENABLER          DmaEnabler,
  [in]           size_t                 Length,
  [in, optional] PWDF_OBJECT_ATTRIBUTES Attributes,
  [out]          WDFCOMMONBUFFER        *CommonBuffer
);

パラメーター

[in] DmaEnabler

WdfDmaEnablerCreate の以前の呼び出しによってドライバーが取得した DMA イネーブラー オブジェクトへのハンドル。

[in] Length

新しいバッファーの目的のサイズ (バイト単位)。 許容される最大バッファー サイズは (MAXULONG - PAGE_SIZE) バイトです。

[in, optional] Attributes

共通バッファー オブジェクトのオブジェクト属性を指定する WDF_OBJECT_ATTRIBUTES 構造体へのポインター。 (構造体の ParentObject メンバーは NULL である必要があります)。このパラメーターは省略可能であり、WDF_NO_OBJECT_ATTRIBUTESできます。

[out] CommonBuffer

共通バッファー オブジェクトへのハンドルを受け取る WDFCOMMONBUFFER 型の変数へのポインター。

戻り値

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

リターン コード 説明
STATUS_INVALID_PARAMETER
 ドライバーが無効なパラメーターを指定しました。
STATUS_INSUFFICIENT_RESOURCES
 フレームワークで共通バッファー オブジェクトを割り当てられなかったか、システムがバッファーを割り当てませんでした。
 

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

注釈

WdfCommonBufferCreate メソッドはメモリを割り当て、ドライバーとデバイスの両方が DMA 操作のために同時にアクセスできるようにメモリをマップします。 ドライバーが WdfCommonBufferCreate を呼び出した後、ドライバーは次の手順を実行する必要があります。

ドライバーは通常、EvtDriverDeviceAdd コールバック関数内から WdfCommonBufferCreate を呼び出します。

ドライバーが WdfDmaEnablerCreate を呼び出す前に、 WdfDeviceSetAlignmentRequirement を呼び出してバッファー配置要件を設定できます。 ドライバーが WdfDeviceSetAlignmentRequirement を呼び出さない場合、バッファーは単語の境界に配置されます。 ドライバーが複数の DMA イネーブラーを作成し、それぞれが異なるバッファーアラインメント要件を持つ場合、ドライバーは WdfDmaEnablerCreate の各呼び出しの前に WdfDeviceSetAlignmentRequirement を呼び出すことができます。

WdfDeviceSetAlignmentRequirement でドライバーが指定した配置要件とは異なる配置要件を持つ共通バッファーを作成するために、ドライバーは WdfCommonBufferCreate ではなく WdfCommonBufferCreateWithConfig を呼び出すことができます。

オペレーティング システムは、割り当てる共通バッファーでキャッシュされたメモリを有効にするかどうかを決定します。 この決定は、プロセッサ アーキテクチャとデバイス バスに基づいています。

x86 ベース、x64 ベース、および Itanium ベースのプロセッサを搭載したコンピューターでは、キャッシュされたメモリが有効になります。 ARM または ARM 64 ベースのプロセッサを搭載したコンピューターでは、オペレーティング システムですべてのデバイスに対してキャッシュされたメモリが自動的に有効にされるわけではありません。 システムは、各デバイスの ACPI_CCA メソッドに依存して、デバイスがキャッシュに一貫性があるかどうかを判断します。

WdfCommonBufferCreate の DmaEnabler パラメーターが指定する DMA イネーブラー オブジェクトは、新しい共通バッファー オブジェクトの親オブジェクトになります。 ドライバーはこの親を変更できません。また、WDF_OBJECT_ATTRIBUTES構造体の ParentObject メンバーは NULL である必要があります。 フレームワークは、親 DMA イネーブラー オブジェクトを削除すると、各共通バッファー オブジェクトを削除します。 または、 WdfObjectDelete を呼び出して、共通バッファー オブジェクトを明示的に削除することもできます。

一般的なバッファーの詳細については、「共通バッファーの 使用」を参照してください。

例

次のコード例は、共通バッファーを取得する方法を示しています。 この例では、 DevExt ポインターによって識別されるドライバー定義のコンテキスト空間に共通バッファーに関する情報を格納します。

DevExt->CommonBufferSize = sizeof(COMMON_BUFFER_STRUCT);  // Your structure size
status = WdfCommonBufferCreate(
                               DevExt->DmaEnabler,
                               DevExt->CommonBufferSize,
                               WDF_NO_OBJECT_ATTRIBUTES,
                               &DevExt->CommonBuffer
                               );
if (status == STATUS_SUCCESS) {
    DevExt->CommonBufferBaseVA = 
        WdfCommonBufferGetAlignedVirtualAddress(DevExt->CommonBuffer);
    DevExt->CommonBufferBaseLA =
        WdfCommonBufferGetAlignedLogicalAddress(DevExt->CommonBuffer); 
}

要件

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

こちらもご覧ください

EvtDriverDeviceAdd

WDF_OBJECT_ATTRIBUTES

WdfCommonBufferCreateWithConfig

WdfCommonBufferGetAlignedLogicalAddress

WdfCommonBufferGetAlignedVirtualAddress

WdfDeviceSetAlignmentRequirement

WdfDmaEnablerCreate