PBUILD_SCATTER_GATHER_LIST_EX 콜백 함수(wdm.h)
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 구조체에 대한 포인터입니다. 이 구조체는 드라이버의 버스 master 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일 수 있습니다. DMA_SYNCHRONOUS_CALLBACK 플래그가 설정되고 ScatterGatherList 및 ExecutionRoutine이 모두 NULL이거나 DMA_SYNCHRONOUS_CALLBACK 플래그가 설정되지 않고 ExecutionRoutine이 NULL인 경우 BuildScatterGatherListEx 호출이 실패합니다.
반환 값
BuildScatterGatherListEx 는 호출이 성공하면 STATUS_SUCCESS 반환합니다. 가능한 오류 반환 값에는 다음 상태 코드가 포함됩니다.
반환 코드 | 설명 |
---|---|
STATUS_INVALID_PARAMETERS | 호출자가 전달한 잘못된 매개 변수 값으로 인해 루틴이 실패했습니다. |
STATUS_BUFFER_TOO_SMALL | ScatterGatherBuffer의 호출자 제공 버퍼가 너무 작아서 분산/수집 목록을 포함할 수 없습니다. |
STATUS_INSUFFICIENT_RESOURCES | 루틴이 DMA 전송에 필요한 리소스를 할당하지 못했습니다. |
설명
BuildScatterGatherListEx*는 이름으로 직접 호출할 수 있는 시스템 루틴이 아닙니다. 이 루틴은 *DMA_OPERATIONS 구조체에서 반환된 주소의 포인터로만 호출할 수 있습니다. 드라이버는 DeviceDescription 매개 변수의 Version 멤버가 DEVICE_DESCRIPTION_VERSION3 설정된 IoGetDmaAdapter를 호출하여 이 루틴의 주소를 가져옵니다. IoGetDmaAdapter가 NULL을 반환하는 경우 플랫폼에서 루틴을 사용할 수 없습니다.
버스 master 어댑터에만 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 가 반환된 후 할당된 리소스 및 분산/수집 목록을 사용할 수 있습니다. 이 경우 드라이버는 NULL이 아닌 유효한 ScatterGatherList 포인터를 제공해야 합니다. 또한 드라이버 시작 DMA 전송이 완료되면 드라이버는 FreeAdapterObject 루틴을 호출하여 BuildScatterGatherListEx 가 어댑터 개체에 할당한 리소스를 해제해야 합니다.
BuildScatterGatherListEx 는 BuildScatterGatherList 루틴의 확장 버전입니다. 다음 목록에는 확장 버전에서만 사용할 수 있는 기능이 요약되어 있습니다.
기능 | Description |
---|---|
시작 오프셋 | 호출 드라이버는 MDL 체인의 시작 부분에 있는 첫 번째 버퍼 주소에서 전송을 시작하는 대신 분산/수집 DMA 전송에 대한 시작 오프셋을 지정할 수 있습니다. |
할당 요청 취소 | DMA 어댑터가 DMA 리소스를 기다리기 위해 대기 중인 경우 드라이버는 CancelAdapterChannel 을 호출하여 보류 중인 할당 요청을 취소할 수 있습니다. |
동기 콜백 | 드라이버는 DMA_SYNCHRONOUS_CALLBACK 플래그를 설정하여 BuildScatterGatherListEx가 반환되기 전에 드라이버 제공 AdapterListControl 루틴을 호출 스레드에서 호출하도록 요청할 수 있습니다. |
요구 사항
요구 사항 | 값 |
---|---|
지원되는 최소 클라이언트 | Windows 8 사용하여 사용할 수 있습니다. |
대상 플랫폼 | 데스크톱 |
헤더 | wdm.h(Wdm.h, Ntddk.h, Ntifs.h 포함) |
IRQL | DISPATCH_LEVEL |
추가 정보
피드백
https://aka.ms/ContentUserFeedback
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요.다음에 대한 사용자 의견 제출 및 보기