WdfCommonBufferCreateWithConfig 関数 (wdfcommonbuffer.h)

[アーティクル]
02/26/2024

[KMDF にのみ適用]

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

構文

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

パラメーター

[in] DmaEnabler

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

[in] Length

新しいバッファーの目的のサイズ (バイト単位)。

[in] Config

バッファーに関する構成情報を含む WDF_COMMON_BUFFER_CONFIG 構造体へのポインター。

[in, optional] Attributes

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

[out] CommonBuffer

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

戻り値

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

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

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

注釈

WdfCommonBufferCreateWithConfig メソッドはメモリを割り当て、ドライバーとデバイスの両方が DMA 操作のために同時にアクセスできるようにメモリをマップします。

さらに、 WdfCommonBufferCreateWithConfig を使用すると、ドライバーはバッファーのバッファー配置要件を指定できます。バッファー配置要件は、ドライバーが WdfDeviceSetAlignmentRequirement を呼び出したときに指定したバッファー配置要件をオーバーライドします。 WdfCommonBufferCreate ではなく WdfCommonBufferCreateWithConfig を使用できます。WdfDeviceSetAlignmentRequirement が指定したバッファーとは異なる配置要件を持つバッファーをドライバーで作成する場合。

ドライバーが WdfCommonBufferCreateWithConfig を呼び出した後、ドライバーは次の手順を実行する必要があります。

WdfCommonBufferGetAlignedVirtualAddress を呼び出して、ドライバーが使用できるバッファーの仮想アドレスを取得します。
WdfCommonBufferGetAlignedLogicalAddress を呼び出して、デバイスが使用できるバッファーの論理アドレスを取得します。

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

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

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

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

例

次のコード例では、 WDF_COMMON_BUFFER_CONFIG 構造体を初期化し、32 バイト境界に配置された 10 バイトのバッファーを作成します。

WDF_COMMON_BUFFER_CONFIG  commonBufConfig;
WDFCOMMONBUFFER  commonBuffer;

WDF_COMMON_BUFFER_CONFIG_INIT(
                              &commonBufConfig,
                              FILE_32_BYTE_ALIGNMENT
                              );

status = WdfCommonBufferCreateWithConfig(
                                         DmaEnabler,
                                         10,
                                         &commonBufConfig,
                                         WDF_NO_OBJECT_ATTRIBUTES,
                                         &commonBuffer
                                         );
if (!NT_SUCCESS (status)) {
    return status;
}

要件

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