WdfDmaTransactionAllocateResources 함수(wdfdmatransaction.h)

[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 반환합니다. 그렇지 않으면 이 메서드는 다음 값 중 하나를 반환합니다.

반환 코드	설명
파라미터 값이 잘못되었습니다	DmaDirection 매개 변수에 잘못된 값이 포함되어 있습니다.
상태_불충분한_리소스	맵 레지스터 요청 수가 인에이블러에 할당된 수를 초과하거나 이전에 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)