WdfCommonBufferCreateWithConfig 函式（wdfcommonbuffer.h）

發行項
02/07/2025

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

傳回碼	描述
STATUS_INVALID_PARAMETER	驅動程式提供無效的參數。
STATUS_INSUFFICIENT_RESOURCES	架構無法配置通用緩衝區物件，或系統無法配置緩衝區。

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

言論

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

此外，WdfCommonBufferCreateWithConfig 可讓您的驅動程式指定緩衝區的緩衝區對齊需求。緩衝區對齊需求會覆寫驅動程式在呼叫 WdfDeviceSetAlignmentRequirement 時所指定的緩衝區對齊需求。如果您的驅動程式可以使用 WdfCommonBufferCreateWithConfig，而不是 WdfCommonBufferCreate，如果您希望驅動程式建立的緩衝區具有與 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
標頭	wdfcommonbuffer.h （包括 WdfCommonBuffer.h）
連結庫	Wdf01000.sys （請參閱架構連結庫版本控制。）
IRQL	PASSIVE_LEVEL
DDI 合規性規則	DriverCreate（kmdf），KmdfIrql（kmdf），KmdfIrql2（kmdf），KmdfIrqlExplicit（kmdf）