PMAP_TRANSFER_EX 콜백 함수(wdm.h)

아티클
03/01/2024

MapTransferEx 루틴은 분산/수집 목록의 실제 주소를 DMA 전송을 수행하는 데 필요한 논리적 주소에 매핑하도록 맵 레지스터를 설정합니다.

구문

PMAP_TRANSFER_EX PmapTransferEx;

NTSTATUS PmapTransferEx(
  [in]            PDMA_ADAPTER DmaAdapter,
  [in]            PMDL Mdl,
  [in]            PVOID MapRegisterBase,
  [in]            ULONGLONG Offset,
  [in]            ULONG DeviceOffset,
  [in, out]       PULONG Length,
  [in]            BOOLEAN WriteToDevice,
  [out, optional] PSCATTER_GATHER_LIST ScatterGatherBuffer,
  [in]            ULONG ScatterGatherBufferLength,
  [in, optional]  PDMA_COMPLETION_ROUTINE DmaCompletionRoutine,
  [in, optional]  PVOID CompletionContext
)
{...}

매개 변수

[in] DmaAdapter

DMA_ADAPTER 구조체에 대한 포인터입니다. 이 구조체는 드라이버의 버스 master DMA 디바이스 또는 시스템 DMA 채널을 나타내는 어댑터 개체입니다. 호출자는 IoGetDmaAdapter 루틴에 대한 이전 호출에서 이 포인터를 얻었습니다.

[in] Mdl

가상 메모리의 잠긴 버퍼 컬렉션에 대한 실제 페이지 레이아웃을 설명하는 MDL 체인에 대한 포인터입니다. DMA 전송에 대한 분산/수집 목록은 Offset 및 Length 매개 변수로 지정된 이 메모리의 영역을 사용합니다. MDL 체인에 대한 자세한 내용은 MDL 사용을 참조하세요.

[in] MapRegisterBase

어댑터 개체에 할당된 맵 레지스터에 대한 핸들입니다. 호출자는 이전에 AllocateAdapterChannelEx 루틴에서 이 핸들을 얻었습니다.

[in] Offset

MDL 체인에서 설명하는 메모리 시작 부분의 바이트 오프셋입니다. 이 오프셋은 DMA 전송에 사용되는 I/O 데이터 버퍼의 시작을 지정합니다. 호출자에게 분산/수집 목록을 제공하는 경우 이 오프셋은 목록에서 첫 번째 버퍼 조각의 시작 주소를 결정합니다. MDL 체인의 MDL이 총 N바이트의 메모리를 설명하는 경우 Offset 의 유효한 값은 0~N-1 범위에 있습니다. 자세한 내용은 설명 부분을 참조하세요.

[in] DeviceOffset

대상 디바이스의 데이터 레지스터 또는 디바이스의 기본 주소에서 FIFO의 바이트 오프셋입니다. 이 매개 변수는 시스템 DMA 컨트롤러에서 액세스할 수 있는 여러 FIDO가 있는 디바이스에 적용됩니다. 이 매개 변수는 시스템 DMA 전송에만 사용됩니다. 버스 master 전송의 경우 이 매개 변수를 0으로 설정합니다.

[in, out] Length

DMA 전송에 사용되는 I/O 데이터 버퍼의 길이(바이트)를 포함하는 변수에 대한 포인터입니다. 항목에서 이 변수는 호출 드라이버에서 요청한 길이를 포함합니다. 반환하기 전에 루틴은 매핑된 버퍼의 실제 길이를 이 변수에 씁니다. MapTransferEx에서 반환되는 *Length 값은 매핑된 바이트 수를 나타냅니다. 맵 레지스터의 수와 분산/수집 버퍼 크기가 호출자가 요청한 전체 길이를 매핑하기에 충분한 경우 *Length 의 입력 및 출력 값은 동일합니다. MDL 체인의 MDL이 총 N바이트의 메모리를 설명하는 경우 유효한 값인 *Length 는 0에서 N-Offset 범위입니다.

[in] WriteToDevice

DMA 전송 방향입니다. 메모리에서 디바이스로 데이터를 전송하는 쓰기 작업의 경우 이 매개 변수를 TRUE 로 설정합니다. 디바이스에서 메모리로 데이터를 전송하는 읽기 작업의 경우 이 매개 변수를 FALSE 로 설정합니다.

[out, optional] ScatterGatherBuffer

루틴이 DMA 전송에 대한 분산/수집 목록을 작성하는 호출자 할당 버퍼에 대한 포인터입니다. 이 목록은 SCATTER_GATHER_ELEMENT 배열 바로 뒤에 오는 SCATTER_GATHER_LIST 구조체로 시작합니다. 버스 master DMA 디바이스를 사용하는 드라이버의 경우 ScatterGatherBuffer는 필수 매개 변수입니다. 시스템 DMA 컨트롤러를 사용하는 드라이버의 경우 ScatterGatherBuffer 매개 변수는 선택 사항이며 NULL일 수 있습니다. 자세한 내용은 설명 부분을 참조하세요.

[in] ScatterGatherBufferLength

ScatterGatherBuffer 매개 변수가 가리키는 버퍼의 크기(바이트)입니다. 할당된 버퍼 크기는 분산/수집 목록과 운영 체제가 이 버퍼에 저장하는 내부 데이터를 포함할 만큼 커야 합니다. 필요한 버퍼 크기를 확인하려면 GetDmaTransferInfo 또는 CalculateScatterGatherList 루틴을 호출합니다. ScatterGatherBuffer가 NULL인 경우 ScatterGatherBufferLength를 0으로 설정합니다.

[in, optional] DmaCompletionRoutine

DMA 전송이 완료될 때 호출자가 제공한 DmaCompletionRoutine 루틴에 대한 포인터입니다. 대상 디바이스가 DMA 완성 인터럽트 생성 시스템 DMA 컨트롤러를 사용하는 경우 이 루틴이 호출됩니다. DmaCompletionRoutine 루틴은 DMA 전송이 완료된 후 DISPATCH_LEVEL 호출됩니다. 시스템 DMA 어댑터의 경우 이 매개 변수는 선택 사항이며 NULL일 수 있습니다. 버스 master 어댑터의 경우 이 매개 변수를 NULL로 설정합니다.

[in, optional] CompletionContext

DmaCompletionRoutine 루틴에 대한 드라이버 결정 컨텍스트입니다. 이 컨텍스트는 DmaCompletionRoutine 루틴에 CompletionContext 매개 변수로 제공됩니다. DmaCompletionRoutine 매개 변수가 NULL인 경우 CompletionContext를 NULL로 설정합니다.

반환 값

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

반환 코드	설명
STATUS_INVALID_PARAMETERS	호출자가 전달한 잘못된 매개 변수 값으로 인해 루틴이 실패했습니다.
STATUS_BUFFER_TOO_SMALL	ScatterGatherBuffer의 호출자 제공 버퍼가 너무 작아서 분산/수집 목록을 포함할 수 없습니다.
STATUS_INSUFFICIENT_RESOURCES	루틴이 DMA 전송에 필요한 리소스를 할당하지 못했습니다.
STATUS_CANCELLED	이 전송이 취소되었습니다.

설명

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

시스템 DMA 컨트롤러를 사용하는 전송의 경우 호출자는 옵션으로 전송이 완료되면 호출되는 DmaCompletionRoutine 콜백 루틴을 제공할 수 있습니다. 운영 체제는 시스템 DMA 컨트롤러의 DMA 완료 중단에 대한 응답으로 이 콜백을 예약합니다.

MapTransferEx에서 설정할 수 있는 맵 레지스터 수는 드라이버가 IoGetDmaAdapter에서 얻은 최대값을 초과할 수 없습니다.

Mdl, Offset 및 Length 매개 변수는 요청된 DMA 전송에 대한 I/O 데이터 버퍼를 설명합니다. 할당된 맵 레지스터 수가 이 버퍼의 모든 메모리를 매핑하기에 충분하지 않거나 ScatterGatherBuffer 가 가리키는 분산/수집 버퍼가 전체 버퍼를 설명할 만큼 크지 않을 수 있습니다. MapTransferEx 는 *Length 에 출력 값을 작성하여 드라이버에 요청된 DMA 전송에 대한 버퍼 메모리의 양을 루틴에 의해 매핑되었는지 알려줍니다. 루틴은 ScatterGatherBuffer가 가리키는 버퍼에 분산/수집 목록을 씁니다. 이 목록에서는 루틴에 의해 성공적으로 매핑된 버퍼 조각에 대해 설명합니다.

MapTransferEx 호출에 성공하면 MapTransferEx는 반환되기 전에 *Length 출력 값을 씁니다. 호출자가 DmaCompletionRoutine을 지정하는 경우 업데이트된 *Length 출력 값은 DmaCompletionRoutine 이 실행되기 전에 항상 기록됩니다. 자세한 내용은 MapTransferEx에 대한 여러 호출을 참조하세요.

Offset 매개 변수는 I/O 데이터 버퍼의 메모리를 설명하는 MDL 체인의 시작 오프셋을 지정합니다. 예를 들어 MDL 체인에 MDL 및 MDL의 두 MDL이 포함되어 있고 MDL은 N바이트의 메모리를 설명하고 MDL은 N 1바이트를 설명한다고 가정합니다. Offset = N이면 여기서 N < N < + N은 MDL에서 설명하는 메모리를 포함하지 않으며 MDL의 설명된 메모리에서 N - N 바이트의 오프셋에서 시작합니다.

전송에서 시스템 DMA 컨트롤러를 사용하는 경우 호출자는 ScatterGatherBuffer = NULL을 설정할 수 있습니다. 이 경우 MapTransferEx 는 내부적으로 할당된 기본 버퍼를 사용하여 분산/수집 목록을 보유합니다. 기본 버퍼는 하나 이상의 요소의 분산/수집 목록을 포함할 만큼 충분히 커야 합니다. 기본 버퍼가 많은 요소의 분산/수집 전송에 사용되는 경우 MapTransferEx 에 대한 많은 호출이 전송을 완료해야 할 수 있습니다. DMA 컨트롤러 하드웨어가 분산/수집 전송을 지원하는 경우 기본 버퍼를 사용하면 성능이 저하될 수 있습니다.

ScatterGatherBuffer가 NULL이 아니고 ScatterGatherBufferSize가 너무 작은 크기를 지정하여 하나 이상의 요소의 분산/수집 목록을 포함할 수 없는 경우 MapTransferEx가 실패하고 STATUS_INVALID_PARAMETER 반환합니다.

MapTransferEx 는 MapTransfer 루틴의 확장 버전입니다. 확장 버전은 다음과 같은 이점이 있습니다.

MapTransferEx 는 한 번의 호출로 MDL 체인의 모든 버퍼 조각을 처리할 수 있지만 MapTransfer 는 호출당 물리적으로 연속된 버퍼 조각을 하나만 처리할 수 있습니다.
MapTransferEx 는 한 번의 호출로 전체 분산/수집 목록을 생성할 수 있지만 MapTransfer 는 호출당 하나의 분산/수집 목록 요소만 생성할 수 있습니다.
MapTransferEx 는 한 번의 호출로 분산/수집 목록의 모든 버퍼 조각을 매핑할 수 있지만 MapTransfer 는 호출당 물리적으로 연속된 버퍼 조각을 하나만 매핑할 수 있습니다.
MapTransferEx 에는 전체 분산/수집 목록에 대한 시작 오프셋만 필요하지만 MapTransfer 에는 물리적으로 인접한 각 버퍼 조각에 대한 시작 가상 주소가 필요합니다.
MapTransferEx 호출은 하나 이상의 MDL을 통해 확장되는 버퍼를 매핑할 수 있지만 MapTransfer 호출은 MDL에서 설명하는 메모리에 물리적으로 연속된 버퍼 조각을 하나만 매핑할 수 있습니다.
시스템 DMA 전송의 경우 MapTransferEx 를 사용하면 호출자가 전송이 완료된 후 알림을 받을 DmaCompletionRoutine 콜백 루틴을 제공할 수 있지만 MapTransfer 는 DMA 전송이 완료될 때 호출자에게 알리는 방법을 제공하지 않습니다.

MapTransferEx에 대한 각 성공적인 호출 뒤에 FlushAdapterBuffersEx 루틴에 대한 해당 호출이 이어서야 합니다. MapTransferEx 호출 다음에 오는 FlushAdapterBuffersEx 호출은 다음 MapTransferEx 호출이 발생하기 전에 발생해야 합니다. CancelMappedTransfer 루틴에 대한 호출이 이전 MapTransferEx 호출에서 요청한 매핑된 전송을 취소하는 데 성공하더라도 FlushAdapterBuffersEx 호출이 필요합니다.

자세한 내용은 MapTransferEx 루틴 사용을 참조하세요.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 8 시작해서 사용할 수 있습니다.
대상 플랫폼	데스크톱
헤더	wdm.h(Wdm.h, Ntddk.h, Ntifs.h 포함)
IRQL	<= DISPATCH_LEVEL