WdfCommonBufferCreate 函式 (wdfcommonbuffer.h)

發行項
02/26/2024

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

傳回碼	Description
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); 
}

規格需求

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