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

DMA enabler 物件的句柄，由先前呼叫 WdfDmaEnablerCreate 取得的驅動程式。

[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。否則，這個方法可能會傳回下列其中一個值：

傳回碼	Description
STATUS_INVALID_PARAMETER	驅動程式提供了無效的參數。
STATUS_INSUFFICIENT_RESOURCES	架構無法配置一般緩衝區物件，或系統無法配置緩衝區。

如果驅動程式提供無效的物件句柄，就會發生錯誤檢查。

備註

WdfCommonBufferCreateWithConfig 方法會配置記憶體並加以對應，讓驅動程式和裝置可以同時存取 DMA 作業。

此外， WdfCommonBufferCreateWithConfig 可讓您的驅動程式指定緩衝區的緩衝區對齊需求。緩衝區對齊需求會覆寫驅動程式在呼叫 WdfDeviceSetAlignmentRequirement 時所指定的緩衝區對齊需求。如果您希望驅動程式建立的緩衝區與 WdfDeviceSetAlignmentRequirement 所指定的緩衝區不同，則可以使用 WdfCommonBufferCreateWithConfig，而不是 WdfCommonBufferCreate。

在驅動程式呼叫 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;
}

規格需求

需求	值
目標平台	Universal
最低 KMDF 版本	1.1
標頭	wdfcommonbuffer.h (包含 WdfCommonBuffer.h)
程式庫	Wdf01000.sys (請參閱 Framework Library Versioning.)
IRQL	PASSIVE_LEVEL
DDI 合規性規則	DriverCreate (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf)