次の方法で共有

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 呼び出した後、ドライバーは次の条件を満たす必要があります。

  • WdfCommonBufferGetAlignedVirtualAddress 呼び出して、ドライバーが使用できるバッファーの仮想アドレスを取得します。
  • WdfCommonBufferGetAlignedLogicalAddress 呼び出して、デバイスが使用できるバッファーの論理アドレスを取得します。
ドライバーは通常、EvtDriverDeviceAdd コールバック関数内から WdfCommonBufferCreate 呼び出します。

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

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
ヘッダー wdfcommonbuffer.h (WdfCommonBuffer.h を含む)
ライブラリ Wdf01000.sys (フレームワーク ライブラリのバージョン管理を参照)。
IRQL PASSIVE_LEVEL
DDI コンプライアンス規則 を する DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

関連項目

EvtDriverDeviceAdd の

WDF_OBJECT_ATTRIBUTES

WdfCommonBufferCreateWithConfig

WdfCommonBufferGetAlignedLogicalAddress

WdfCommonBufferGetAlignedVirtualAddress

WdfDeviceSetAlignmentRequirement の

WdfDmaEnablerCreate