WdfCommonBufferCreate 函式（wdfcommonbuffer.h）

發行項
02/07/2025

[僅適用於 KMDF]

WdfCommonBufferCreate 方法會建立記憶體緩衝區，讓驅動程式和直接記憶體存取（DMA）裝置可以同時存取。

語法

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

參數

[in] DmaEnabler

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

[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 啟用者，每個啟用器都有不同的緩衝區對齊需求，則驅動程式可以在每次 呼叫 WdfDmaEnablerCreate之前呼叫 WdfDeviceSetAlignmentRequirement。

若要建立一般緩衝區，其對齊需求與使用 WdfDeviceSetAlignmentRequirement指定的驅動程式不同，驅動程式可以呼叫 WdfCommonBufferCreateWithConfig，而不是 WdfCommonBufferCreate。

作系統會決定是否要在要配置的通用緩衝區中啟用快取記憶體。該決策是以處理器架構和裝置總線為基礎。

在 x86 型、x64 型和 Itanium 型處理器的電腦上，會啟用快取的記憶體。在具有ARM或ARM 64處理器的電腦上，作系統不會自動啟用所有裝置的快取記憶體。系統依賴每個裝置的 ACPI_CCA 方法，判斷裝置是否快取一致。

WdfCommonBufferCreate 指定之 DmaEnabler 參數的 DMA enabler 物件會成為新通用緩衝區對象的父物件。驅動程式無法變更此父代，而且 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）