共用方式為


WdfCommonBufferCreateWithConfig 函式 (wdfcommonbuffer.h)

[僅適用於 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 之後,驅動程序必須:

驅動程式通常會從其 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)

另請參閱

EvtDriverDeviceAdd

WDF_COMMON_BUFFER_CONFIG

WDF_OBJECT_ATTRIBUTES

WdfCommonBufferCreate

WdfCommonBufferGetAlignedLogicalAddress

WdfCommonBufferGetAlignedVirtualAddress

WdfDeviceSetAlignmentRequirement

WdfDmaEnablerCreate