WdfCommonBufferCreate 함수(wdfcommonbuffer.h)

[KMDF에만 적용]

WdfCommonBufferCreate 메서드는 드라이버와 DMA(직접 메모리 액세스) 디바이스가 동시에 액세스할 수 있는 메모리 버퍼를 만듭니다.

구문

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

매개 변수

[in] DmaEnabler

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

[in] Length

새 버퍼의 원하는 크기(바이트)입니다. 허용되는 최대 버퍼 크기는 (MAXULONG - PAGE_SIZE) 바이트입니다.

[in, optional] Attributes

공통 버퍼 개체의 개체 특성을 지정하는 WDF_OBJECT_ATTRIBUTES 구조체에 대한 포인터입니다. 구조체의 ParentObject 멤버는 NULL이어야 합니다. 이 매개 변수는 선택 사항이며 WDF_NO_OBJECT_ATTRIBUTES 수 있습니다.

[out] CommonBuffer

공통 버퍼 개체에 대한 핸들을 수신하는 WDFCOMMONBUFFER 형식 변수에 대한 포인터입니다.

반환 값

WdfCommonBufferCreate 는 작업이 성공하면 STATUS_SUCCESS 반환합니다. 그렇지 않으면 이 메서드는 다음 값 중 하나를 반환할 수 있습니다.

드라이버가 잘못된 개체 핸들을 제공하는 경우 버그 검사 발생합니다.

설명

WdfCommonBufferCreate 메서드는 메모리를 할당하고 매핑하여 드라이버와 디바이스가 DMA 작업을 위해 동시에 액세스할 수 있도록 합니다. 드라이버가 WdfCommonBufferCreate를 호출한 후 드라이버는 다음을 수행해야 합니다.

• WdfCommonBufferGetAlignedVirtualAddress를 호출하여 드라이버에서 사용할 수 있는 버퍼의 가상 주소를 가져옵니다.
• WdfCommonBufferGetAlignedLogicalAddress를 호출하여 디바이스에서 사용할 수 있는 버퍼의 논리적 주소를 가져옵니다.

드라이버가 WdfDmaEnablerCreate를 호출하기 전에 WdfDeviceSetAlignmentRequirement 를 호출하여 버퍼 맞춤 요구 사항을 설정할 수 있습니다. 드라이버가 WdfDeviceSetAlignmentRequirement를 호출하지 않으면 버퍼가 단어 경계에 맞춰집니다. 드라이버가 각각 다른 버퍼 맞춤 요구 사항이 있는 여러 DMA 지원자를 만드는 경우 드라이버는 WdfDmaEnablerCreate를 호출하기 전에 WdfDeviceSetAlignmentRequirement를 호출할 수 있습니다.

WdfDeviceSetAlignmentRequirement로 지정된 드라이버의 맞춤 요구 사항과 다른 맞춤 요구 사항이 있는 공통 버퍼를 만들려면 드라이버는 WdfCommonBufferCreate 대신 WdfCommonBufferCreateWithConfig를 호출할 수 있습니다.

운영 체제는 할당할 공통 버퍼에서 캐시된 메모리를 사용할지 여부를 결정합니다. 이 결정은 프로세서 아키텍처 및 디바이스 버스를 기반으로 합니다.

x86 기반, x64 기반 및 Itanium 기반 프로세서가 있는 컴퓨터에서는 캐시된 메모리가 사용하도록 설정됩니다. ARM 또는 ARM 64 기반 프로세서가 있는 컴퓨터에서 운영 체제는 모든 디바이스에 대해 캐시된 메모리를 자동으로 사용하도록 설정하지 않습니다. 시스템은 각 디바이스에 대한 ACPI_CCA 메서드를 사용하여 디바이스가 캐시 일관성인지 여부를 확인합니다.

WdfCommonBufferCreate의 DmaEnabler 매개 변수가 지정하는 DMA 인에이블러 개체는 새 공통 버퍼 개체의 부모 개체가 됩니다. 드라이버는 이 부모를 변경할 수 없으며 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); 
}

요구 사항

추가 정보

EvtDriverDeviceAdd

WDF_OBJECT_ATTRIBUTES

WdfCommonBufferCreateWithConfig

WdfCommonBufferGetAlignedLogicalAddress

WdfCommonBufferGetAlignedVirtualAddress

WdfDeviceSetAlignmentRequirement

WdfDmaEnablerCreate