PMAP_TRANSFER_EX 콜백 함수(wdm.h)
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 반환합니다. 가능한 오류 반환 값에는 다음 상태 코드가 포함됩니다.
| 반환 코드 | 설명 |
|---|---|
|
호출자가 전달한 잘못된 매개 변수 값으로 인해 루틴이 실패했습니다. |
|
ScatterGatherBuffer의 호출자 제공 버퍼가 너무 작아서 분산/수집 목록을 포함할 수 없습니다. |
|
루틴이 DMA 전송에 필요한 리소스를 할당하지 못했습니다. |
|
이 전송이 취소되었습니다. |
설명
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 루틴 사용을 참조하세요.
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows 8 시작해서 사용할 수 있습니다. |
| 대상 플랫폼 | 데스크톱 |
| 헤더 | wdm.h(Wdm.h, Ntddk.h, Ntifs.h 포함) |
| IRQL | <= DISPATCH_LEVEL |