PBUILD_SCATTER_GATHER_LIST_EX 콜백 함수(wdm.h)

아티클
07/16/2024

BuildScatterGatherListEx 루틴은 DMA 전송에 필요한 리소스를 할당하고, 분산/수집 목록을 작성하고, 드라이버 제공 AdapterListControl 루틴을 호출하여 DMA 전송을 시작합니다.

주의

시스템 DMA 디바이스에 대해 이 루틴을 호출하지 마세요.

통사론

PBUILD_SCATTER_GATHER_LIST_EX PbuildScatterGatherListEx;

NTSTATUS PbuildScatterGatherListEx(
  [in]            PDMA_ADAPTER DmaAdapter,
  [in]            PDEVICE_OBJECT DeviceObject,
  [in]            PVOID DmaTransferContext,
  [in]            PMDL Mdl,
  [in]            ULONGLONG Offset,
  [in]            ULONG Length,
  [in]            ULONG Flags,
  [in, optional]  PDRIVER_LIST_CONTROL ExecutionRoutine,
  [in, optional]  PVOID Context,
  [in]            BOOLEAN WriteToDevice,
  [in]            PVOID ScatterGatherBuffer,
  [in]            ULONG ScatterGatherLength,
  [in, optional]  PDMA_COMPLETION_ROUTINE DmaCompletionRoutine,
  [in, optional]  PVOID CompletionContext,
  [out, optional] PVOID ScatterGatherList
)
{...}

매개 변수

[in] DmaAdapter

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

[in] DeviceObject

DEVICE_OBJECT 구조체에 대한 포인터입니다. 이 구조는 요청된 DMA 작업의 대상 디바이스를 나타내는 PDO(물리적 디바이스 개체)입니다.

[in] DmaTransferContext

초기화된 DMA 전송 컨텍스트에 대한 포인터입니다. 이 컨텍스트는 InitializeDmaTransferContext 루틴에 대한 이전 호출에 의해 초기화되었습니다. 이 컨텍스트는 모든 어댑터 할당 요청에서 고유해야 합니다. 보류 중인 할당 요청을 취소하려면 호출자가 요청에 대한 DMA 전송 컨텍스트를 CancelAdapterChannel 루틴에 제공해야 합니다.

[in] Mdl

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

[in] Offset

분산/수집 DMA 전송의 시작 오프셋입니다. 이 매개 변수는 MDL 체인의 첫 번째 MDL에 있는 버퍼의 시작 부분부터 바이트 오프셋입니다. MDL 체인의 MDL이 총 N바이트의 버퍼 공간을 지정하는 경우 Offset 유효한 값은 0에서 N-1까지의 범위에 있습니다.

[in] Length

DMA 전송의 크기(바이트)입니다. MDL 체인이 총 N바이트의 버퍼 공간을 지정하는 경우 Length 유효한 값은 오프셋범위 1에서 N까지입니다.

[in] Flags

어댑터 채널 할당 플래그입니다. 지원되는 플래그는 다음과 같습니다.

기	의미
DMA_SYNCHRONOUS_CALLBACK	BuildScatterGatherListEx 루틴을 동기적으로 호출합니다. 이 플래그가 설정되고 필요한 DMA 리소스를 즉시 사용할 수 없는 경우 호출이 실패하고 STATUS_INSUFFICIENT_RESOURCES 반환합니다.

DMA_SYNCHRONOUS_CALLBACK 플래그가 설정된 경우 ExecutionRoutine 매개 변수는 선택 사항이며 NULL수 있습니다. 이 플래그가 설정되지 않은 경우 ExecutionRoutine 유효한 비NULL 포인터여야 합니다. 이 플래그에 대한 자세한 내용은 설명 섹션을 참조하세요.

[in, optional] ExecutionRoutine

드라이버에 대한 DMA 전송을 시작하는 드라이버 제공 AdapterListControl 루틴에 대한 포인터입니다. I/O 관리자는 어댑터 개체에 필요한 리소스가 할당된 후 AdapterListControl 루틴을 호출합니다. AdapterListControl 루틴이 반환되면 I/O 관리자가 이 개체에 할당된 어댑터 개체와 리소스를 자동으로 해제합니다.

DMA_SYNCHRONOUS_CALLBACK 플래그가 설정된 경우 ExecutionRoutine 선택 사항이며 NULL수 있습니다. ExecutionRoutine NULL호출자는 BuildScatterGatherListEx의해 할당된 리소스를 사용할 수 있습니다. 자세한 내용은 설명 섹션을 참조하세요.

[in, optional] Context

드라이버로 결정된 어댑터 제어 컨텍스트입니다. 이 컨텍스트는 Context 매개 변수로 AdapterListControl 루틴에 전달됩니다.

[in] WriteToDevice

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

[in] ScatterGatherBuffer

루틴이 DMA 전송에 대한 분산/수집 목록을 작성하는 호출자 할당 버퍼에 대한 포인터입니다. 이 목록은 SCATTER_GATHER_LIST 구조체로 시작하고 그 뒤에 SCATTER_GATHER_ELEMENT 배열이 옵니다.

[in] ScatterGatherLength

ScatterGatherBuffer 매개 변수에 전달된 버퍼의 크기(바이트)입니다. 할당된 버퍼 크기는 분산/수집 목록과 운영 체제가 이 버퍼에 저장하는 내부 데이터를 포함할 수 있을 만큼 커야 합니다. 필요한 버퍼 크기를 계산하려면 GetDmaTransferInfo 호출하거나 calculateScatterGatherList 루틴을 .

[in, optional] DmaCompletionRoutine

사용되지 않습니다. NULL.

[in, optional] CompletionContext

사용되지 않습니다. NULL.

[out, optional] ScatterGatherList

루틴이 DMA 전송에 대한 분산/수집 목록에 대한 포인터를 쓰는 변수에 대한 포인터입니다. 이 목록은 SCATTER_GATHER_ELEMENT 배열에 대한 포인터를 포함하는 SCATTER_GATHER_LIST 구조체로 시작합니다. 이 출력 포인터는 항상 ScatterGatherBuffer 매개 변수 값과 일치합니다.

DMA_SYNCHRONOUS_CALLBACK 플래그가 설정되고 ExecutionRoutine 매개 변수가 NULL경우 ScatterGatherList 유효한 비NULL 포인터여야 합니다. ExecutionRoutine 비-NULL경우 ScatterGatherList 선택 사항이며 호출 드라이버에 분산/수집 목록이 필요하지 않은 경우 NULL 수 있습니다. BuildScatterGatherListEx 호출은 DMA_SYNCHRONOUS_CALLBACK 플래그가 설정되어 있고 ScatterGatherList 및 ExecutionRoutine 모두 NULL경우 또는 DMA_SYNCHRONOUS_CALLBACK 플래그가 설정되지 않고 ExecutionRoutine NULL경우 실패합니다.

반환 값

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

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

발언

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

BuildScatterGatherListEx 버스 마스터 어댑터에만 사용합니다. 시스템 DMA 어댑터에는 이 루틴을 사용하지 마세요.

BuildScatterGatherListEx 호출자가 분산/수집 목록에 버퍼를 할당해야 한다는 점을 제외하고 GetScatterGatherListEx 루틴과 유사합니다.

예를 들어 드라이버는 디바이스 초기화 중에 하나 이상의 분산형/수집 버퍼를 미리 할당할 수 있습니다. 나중에 이러한 버퍼를 사용하는 BuildScatterGatherListEx 호출은 GetScatterGatherListEx 호출이 실패할 수 있는 메모리 가용성이 낮은 조건에서 성공할 수 있습니다.

기본적으로 BuildScatterGatherListEx 요청된 리소스 할당이 완료되길 기다리지 않고 비동기적으로 반환됩니다. 이 반환 후에 호출자는 필요한 경우 CancelAdapterChannel 루틴을 호출하여 보류 중인 할당 요청을 취소할 수 있습니다.

호출 드라이버가 DMA_SYNCHRONOUS_CALLBACK 플래그를 설정하는 경우 BuildScatterGatherListEx 루틴은 다음과 같이 작동합니다.

요청된 리소스를 즉시 사용할 수 없는 경우 buildScatterGatherListEx 리소스를 기다리지 않고, 분산/수집 목록을 작성하지 않으며, AdapterListControl 루틴을 호출하지 않습니다. 대신 BuildScatterGatherListEx 실패하고 STATUS_INSUFFICIENT_RESOURCES 반환합니다.
DMA_SYNCHRONOUS_CALLBACK 플래그가 설정된 경우 드라이버는 AdapterListControl 루틴을 제공할 필요가 없습니다.
드라이버가 AdapterListControl 루틴을 제공하는 경우 DMA_SYNCHRONOUS_CALLBACK 플래그는 BuildScatterGatherListEx가 반환되기 전에 호출 스레드의 컨텍스트에서 이 루틴을 호출해야 나타냅니다.
드라이버가 AdapterListControl 루틴을 제공하지 않으면 BuildScatterGatherListEx가 반환된 후 드라이버는 할당된 리소스 및 분산/수집 목록을 사용할 수. 이 경우 드라이버는 유효한 비NULLScatterGatherList 포인터를 제공해야 합니다. 또한 드라이버 시작 DMA 전송이 완료되면 드라이버는 FreeAdapterObject 루틴을 호출하여 어댑터 개체에 할당된 BuildScatterGatherListEx 리소스를 해제해야 합니다.

BuildScatterGatherListExBuildScatterGatherList 루틴의 확장 버전입니다. 다음 목록에는 확장 버전에서만 사용할 수 있는 기능이 요약되어 있습니다.

특징	묘사
시작 오프셋	호출 드라이버는 MDL 체인의 시작 부분에 있는 첫 번째 버퍼 주소에서 전송을 시작하는 대신 분산/수집 DMA 전송에 대한 시작 오프셋을 지정할 수 있습니다.
할당 요청 취소	DMA 어댑터가 DMA 리소스를 기다리기 위해 대기 중인 경우 드라이버는 CancelAdapterChannel 호출하여 보류 중인 할당 요청을 취소할 수 있습니다.
동기 콜백	드라이버는 DMA_SYNCHRONOUS_CALLBACK 플래그를 설정하여 *BuildScatterGatherListEx가 반환되기 전에 드라이버에서 제공하는 AdapterListControl* 루틴을 호출하도록 요청할 수**.

요구 사항

요구	값
지원되는 최소 클라이언트	Windows 8부터 사용할 수 있습니다.
대상 플랫폼	바탕 화면
헤더	wdm.h(Wdm.h, Ntddk.h, Ntifs.h 포함)
IRQL	DISPATCH_LEVEL