PCREATE_COMMON_BUFFER_FROM_MDL 콜백 함수(wdm.h)

아티클
08/08/2023

CreateCommonBufferFromMdl 루틴은 디바이스 액세스 호환성을 테스트하고 변환 유형에 따라 메모리를 연속 논리 범위에 매핑하여 MDL에서 공통 버퍼를 만들려고 시도합니다. 다른 모든 일반적인 버퍼 할당 함수와 마찬가지로 이 함수는 진행률 보장을 제공하지 않습니다.

구문

PCREATE_COMMON_BUFFER_FROM_MDL PcreateCommonBufferFromMdl;

NTSTATUS PcreateCommonBufferFromMdl(
  [in]  PDMA_ADAPTER DmaAdapter,
  [in]  PMDL Mdl,
  [in]  PDMA_COMMON_BUFFER_EXTENDED_CONFIGURATION ExtendedConfigs,
  [in]  ULONG ExtendedConfigsCount,
  [out] PPHYSICAL_ADDRESS LogicalAddress
)
{...}

매개 변수

[in] DmaAdapter

작업을 수행하는 DMA 어댑터에 대한 포인터를 제공합니다.

[in] Mdl

공통 버퍼에 매핑될 MDL을 제공합니다.

MDL이 공통 버퍼를 백업할 수 있도록 하려면 다음 조건을 충족해야 합니다.

MDL에는 공통 버퍼의 수명 동안 항상 상주하며 시스템 주소 공간에 매핑되는 페이지가 있어야 합니다. 이 작업은 다음 방법으로 수행할 수 있습니다.
MDL은 MmBuildMdlForNonPagedPool을 통해 페이징되지 않은 풀의 버퍼에서 만들어집니다.
MDL은 MmProbeAndLockPages를 통해 잠기고 MmGetSystemAddressForMdlSafe를 통해 시스템 공간에 매핑되었습니다.
MDL의 물리적 페이지는 MmAllocatePagesForMdlEx 를 통해 할당되었으며 MmGetSystemAddressForMdlSafe를 통해 시스템 공간에 매핑되었습니다.
MDL은 페이지 정렬 영역을 나타내야 하며 PAGE_SIZE 배수여야 합니다.
- SubSection 확장 구성을 사용하는 경우 사용되는 MDL의 부분은 페이지 정렬되어야 하며 PAGE_SIZE 배수여야 합니다.
MDL은 연결된 MDL이 아니어야 합니다.
- SubSection 확장 구성을 사용하는 경우 연결된 MDL을 제공할 수 있지만 사용되는 MDL의 부분은 체인의 단일 MDL에 포함되어야 합니다.
DMA 다시 매핑을 사용하지 않는 경우 MDL은 물리적으로 연속된 메모리를 나타내고 디바이스에 액세스할 수 있어야 합니다.

[in] ExtendedConfigs

MDL 백업 공통 버퍼 만들기를 추가로 구성하기 위한 선택적 DMA_COMMON_BUFFER_EXTENDED_CONFIGURATION 구조 배열을 제공합니다.

동일한 DMA_COMMON_BUFFER_EXTENDED_CONFIGURATION_TYPE 여러 구성이 배열에 제공되면 생성에 실패합니다.

[in] ExtendedConfigsCount

ExtendedConfigs 배열의 확장 구성 수를 제공합니다.

[out] LogicalAddress

성공 시 결과 공통 버퍼의 논리적 주소를 제공합니다.

반환 값

CreateCommonBufferFromMdl 은 호출이 성공하면 STATUS_SUCCESS 반환합니다. 가능한 오류 반환 값에는 다음 상태 코드가 포함됩니다.

반환 코드	설명
STATUS_INVALID_PARAMETER	호출자가 호환되지 않는 MDL 또는 확장 구성을 제공했습니다.
STATUS_NOT_SUPPORTED	호출자가 현재 시스템에서 지원되지 않는 확장된 구성을 제공했습니다.
STATUS_INSUFFICIENT_RESOURCES	시스템에는 책 보관 및 매핑 메타데이터를 만들기에 충분한 메모리가 없습니다.

설명

CreateCommonBufferFromMdl 은 이름으로 직접 호출할 수 있는 시스템 루틴이 아닙니다. 이 루틴은 DMA_OPERATIONS 구조에서 반환된 주소의 포인터로만 호출할 수 있습니다. 드라이버는 DeviceDescription 매개 변수의 Version 멤버가 DEVICE_DESCRIPTION_VERSION3 설정된 IoGetDmaAdapter를 호출하여 이 루틴의 주소를 가져옵니다. IoGetDmaAdapter가 NULL을 반환하는 경우 플랫폼에서 루틴을 사용할 수 없습니다.

CreateCommonBufferFromMdl에서 만든 일반적인 버퍼는 FreeCommonBuffer를 통해 제거됩니다. 호출자는 어댑터의 일반적인 버퍼 부기 구조에서 공통 버퍼가 올바르게 제거되도록 시스템 가상 주소를 가상 주소로 제공해야 합니다. 드라이버는 여전히 MDL 및 지원 페이지의 잠금을 해제하고 해제할 책임이 있습니다.

HAL이 백업 메모리 유지 관리를 담당하는 공통 버퍼를 만들려면 AllocateCommonBufferWithBounds를 사용합니다.