WdfCommonBufferCreateWithConfig 함수(wdfcommonbuffer.h)

아티클
08/08/2023

[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

드라이버가 WdfDmaEnablerCreate에 대한 이전 호출을 통해 얻은 DMA 인에이블러 개체에 대한 핸들입니다.

[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를 호출할 때 지정한 버퍼 맞춤 요구 사항을 재정의합니다. 드라이버가 WdfDeviceSetAlignmentRequirement가 지정한 것과 다른 맞춤 요구 사항이 있는 버퍼를 만들려면 드라이버가 WdfCommonBufferCreateCreate 대신 WdfCommonBufferCreateWithConfig를 사용할 수 있습니다.

드라이버가 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)