WdfDmaTransactionAllocateResources 함수(wdfdmatransaction.h)

아티클
08/08/2023

[KMDF에만 적용]

WdfDmaTransactionAllocateResources 메서드는 지정된 트랜잭션 개체에서 배타적이고 반복적인 사용을 위해 단일 패킷 또는 시스템 모드 DMA 인에이블러를 예약합니다. 드라이버는 예약된 리소스를 보유하는 동안 트랜잭션을 여러 번 초기화하고 시작할 수 있습니다.

구문

NTSTATUS WdfDmaTransactionAllocateResources(
  [in] WDFDMATRANSACTION   DmaTransaction,
  [in] WDF_DMA_DIRECTION   DmaDirection,
  [in] ULONG               RequiredMapRegisters,
  [in] PFN_WDF_RESERVE_DMA EvtReserveDmaFunction,
  [in] PVOID               EvtReserveDmaContext
);

매개 변수

[in] DmaTransaction

DMA 리소스를 예약해야 하는 DMA 트랜잭션 개체에 대한 핸들입니다.

[in] DmaDirection

리소스가 예약되는 DMA 전송 방향을 지정하는 WDF_DMA_DIRECTION 형식의 값입니다. 드라이버가 이중 프로필을 지정하지 않은 경우 프레임워크는 이 값을 무시합니다.

[in] RequiredMapRegisters

드라이버가 예약하려는 맵 레지스터의 수입니다. 0이면 프레임워크는 초기화된 트랜잭션에서 필요한 맵 레지스터 수를 파생합니다.

[in] EvtReserveDmaFunction

드라이버의 EvtReserveDma 이벤트 콜백 함수에 대한 포인터입니다.

[in] EvtReserveDmaContext

드라이버의 EvtReserveDma 이벤트 콜백 함수에 제공할 컨텍스트를 포함하는 버퍼에 대한 포인터입니다.

반환 값

WdfDmaTransactionAllocateResources는 작업이 성공하면 STATUS_SUCCESS 반환합니다. 그렇지 않으면 이 메서드는 다음 값 중 하나를 반환합니다.

반환 코드	설명
STATUS_INVALID_PARAMETER	DmaDirection 매개 변수에 잘못된 값이 포함되어 있습니다.
STATUS_INSUFFICIENT_RESOURCES	맵 레지스터 요청 수가 인에이블러에 할당된 수를 초과하거나 이전에 WdfDmaTransactionSetImmediateExecution 이라는 드라이버를 초과하며 요청에 필요한 리소스를 사용할 수 없습니다.
STATUS_INVALID_DEVICE_REQUEST	DMA 버전 3 이상이 사용하도록 설정되지 않았거나 분산형 수집 DMA 인에이 메서드를 호출한 드라이버입니다.

설명

WdfDmaTransactionAllocateResources 는 시스템 DMA 엔진에 맵 레지스터에 대한 요청을 보냅니다. 요청이 처리되면 프레임워크는 드라이버의 EvtReserveDma 이벤트 콜백 함수를 호출합니다. 리소스 예약에 대한 자세한 내용은 DMA 리소스 예약을 참조하세요.

프레임워크 기반 드라이버는 일반적으로 I/O 요청 처리기 내에서 WdfDmaTransactionAllocateResources를 호출합니다. 드라이버는 DMA 인에이블러 개체를 만든 후 EvtDriverDeviceAdd 콜백 함수에서 WdfDmaTransactionAllocateResources를 호출할 수도 있습니다.

분산/수집 DMA 인에이블러를 사용하여 호출되면 WdfDmaTransactionAllocateResources는 검증 도구 버그 검사 발생합니다.

드라이버는 WdfDmaTransactionAllocateResources를 호출하기 전에 DmaTransaction으로 지정된 트랜잭션을 만들어야 합니다. WdfDmaTransactionAllocateResources를 호출한 후 드라이버는 트랜잭션을 초기화하고 시작합니다. 드라이버는 동일한 트랜잭션 개체를 여러 번 다시 초기화하고 다시 초기화할 수 있으므로 맵 레지스터가 HAL로 다시 해제된 다음 다시 할당될 때 트랜잭션 간에 발생하는 지연을 방지할 수 있습니다.

드라이버는 다음과 같은 상황에서 WdfDmaTransactionAllocateResources 를 호출할 수 있습니다.

드라이버는 EvtDevicePrepareHardware 콜백 함수에서 DMA 채널 집합을 받습니다. EvtDevicePrepareHardware에서 드라이버는 DMA 트랜잭션을 초기화하고 WdfDmaTransactionAllocateResources를 호출하여 이 트랜잭션에서 단독으로 사용할 수 있도록 인에이블러를 예약합니다. 또는 드라이버가 요청 처리기에서 WdfDmaTransactionAllocateResources를 호출한 다음 트랜잭션을 여러 번 시작할 수 있습니다.
드라이버는 인에이블러에서 일련의 트랜잭션을 수행해야 합니다. 드라이버는 인에이블러를 예약하고, 동일한 트랜잭션 개체를 사용하여 여러 트랜잭션을 초기화 및 시작한 다음, 인에이블러를 해제합니다.

WdfDmaTransactionAllocateResources를 호출하기 전에 드라이버는 이 예약을 사용하여 시작할 트랜잭션에 필요한 맵 레지스터 수를 결정해야 합니다. 이렇게 하려면 드라이버가 [ADDRESS_AND_SIZE_TO_SPAN_PAGES](.를 호출할 수 있습니다. /wdm/nf-wdm-address_and_size_to_span_pages.md) 매크로 또는 WdfDmaTransactionGetTransferInfo.

WdfDmaTransactionAllocateResources를 호출할 때 드라이버는 인에이블러를 만들 때 요청한 것보다 더 많은 맵 레지스터를 요청해서는 안 됩니다.

비차단 방식으로 WdfDmaTransactionAllocateResources 를 호출하려면 먼저 드라이버가 WdfDmaTransactionSetImmediateExecution을 호출해야 합니다.

WdfDmaTransactionAllocateResources 에는 DMA 버전 3이 필요합니다. DMA 버전 3을 선택하려면 WDF_DMA_ENABLER_CONFIGWdmDmaVersionOverride 멤버를 3으로 설정합니다.

요구 사항

요구 사항	값
대상 플랫폼	유니버설
최소 KMDF 버전	1.11
머리글	wdfdmatransaction.h(Wdf.h 포함)
라이브러리	Wdf01000.sys(프레임워크 라이브러리 버전 관리 참조)
IRQL	<=DISPATCH_LEVEL
DDI 규정 준수 규칙	DriverCreate(kmdf)