PALLOCATE_ADAPTER_CHANNEL 콜백 함수(wdm.h)

아티클
08/08/2023

AllocateAdapterChannel 루틴은 대상 디바이스 개체를 대신하여 DMA 작업을 위해 시스템을 준비한 다음 드라이버 제공 AdapterControl 루틴을 호출하여 DMA 작업을 수행합니다.

구문

PALLOCATE_ADAPTER_CHANNEL PallocateAdapterChannel;

NTSTATUS PallocateAdapterChannel(
  [in] PDMA_ADAPTER DmaAdapter,
  [in] PDEVICE_OBJECT DeviceObject,
  [in] ULONG NumberOfMapRegisters,
  [in] PDRIVER_CONTROL ExecutionRoutine,
  [in] PVOID Context
)
{...}

매개 변수

[in] DmaAdapter

버스 master 어댑터 또는 DMA 컨트롤러를 나타내는 IoGetDmaAdapter에서 반환된 DMA_ADAPTER 구조체에 대한 포인터입니다.

[in] DeviceObject

요청된 DMA 작업의 대상 디바이스를 나타내는 디바이스 개체에 대한 포인터입니다.

[in] NumberOfMapRegisters

전송에 사용할 지도 레지스터 수를 지정합니다. 이 값은 현재 전송 요청을 충족하는 데 필요한 맵 레지스터 수와 IoGetDmaAdapter에서 반환된 사용 가능한 맵 레지스터 수보다 적습니다.

[in] ExecutionRoutine

드라이버 제공 AdapterControl 루틴에 대한 포인터입니다. 루틴은 시스템 DMA 컨트롤러 또는 버스 master 어댑터를 사용할 수 있게 되면 호출됩니다.

[in] Context

AdapterControl 루틴에 전달할 드라이버 결정 컨텍스트에 대한 포인터입니다.

반환 값

이 루틴은 다음 NTSTATUS 값 중 하나를 반환할 수 있습니다.

반환 코드	설명
STATUS_SUCCESS	어댑터 채널이 할당되었습니다. DMA 작업을 시작할 수 있으면 시스템에서 AdapterControl 루틴을 호출합니다.
STATUS_INSUFFICIENT_RESOURCES	NumberOfMapRegisters는 IoGetDmaAdapter에서 반환하는 값보다 큽니다. AdapterControl 루틴은 호출되지 않습니다.

설명

AllocateAdapterChannel 은 이름으로 직접 호출할 수 있는 시스템 루틴이 아닙니다. 이 루틴은 DMA_OPERATIONS 구조에서 반환된 주소의 포인터로만 호출할 수 있습니다. 드라이버는 IoGetDmaAdapter를 호출하여 이 루틴의 주소를 가져옵니다.

드라이버는 AllocateAdapterControl 루틴을 호출하여 드라이버에 대한 DMA 작업을 수행하는 AdapterControl 루틴을 등록합니다. AdapterControl 루틴은 시스템 DMA 컨트롤러 또는 버스 master 어댑터를 사용하여 DMA 작업을 수행합니다.

DMA 작업을 즉시 수행할 수 있는 경우 시스템은 즉시 AdapterControl을 호출합니다. 시스템 DMA 컨트롤러 또는 버스 master 어댑터가 현재 사용 중인 경우 AllocateAdapterChannel은 어댑터를 사용할 수 있을 때까지 AdapterControl을 큐에 대기합니다. 두 경우 모두 AllocateAdapterChannel 은 STATUS_SUCCESS 반환합니다.

시스템에 DMA 작업을 수행할 리소스가 없는 경우 AllocateAdapterChannel 은 STATUS_INSUFFICIENT_RESOURCES 반환합니다. 이 경우 AdapterControl 은 큐에 대기되지 않으며 드라이버는 적절한 오류 코드(예: STATUS_INSUFFICIENT_RESOURCES)로 현재 IRP를 완료해야 합니다.

이 루틴은 지정된 디바이스에 대한 현재 IRP의 전송 요청을 충족하는 데 필요한 하나 이상의 DMA 작업에 대한 DMA 컨트롤러 채널 및 맵 레지스터에 대한 단독 액세스를 예약합니다.

디바이스 개체에 대해 한 번에 하나의 DMA 요청만 큐에 대기할 수 있습니다. 따라서 드라이버는 AdapterControl 루틴 실행이 완료될 때까지 동일한 디바이스 개체에서 다른 DMA 작업에 대해 AllocateAdapterChannel을 다시 호출해서는 안 됩니다. 또한 드라이버는 AdapterControl 루틴 내에서 AllocateAdapterChannel을 호출하지 않아야 합니다.

시스템은 DeviceObject의 CurrentIrp 멤버 값을 AdapterControl의 Irp 매개 변수로 전달합니다. Driver의 StartIo 루틴에서 AllocateAdapterChannel이 호출되면 StartIo가 처리하도록 호출된 IRP를 가리키도록 보장됩니다. 그렇지 않으면 AdapterControl의 Irp 매개 변수를 사용하려면 AllocateAdapterChannel을 호출하기 전에 드라이버가 CurrentIrp를 현재 IRP를 가리키도록 설정해야 합니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 2000부터 사용할 수 있습니다.
대상 플랫폼	데스크톱
헤더	wdm.h(Wdm.h, Ntddk.h, Ntifs.h 포함)
IRQL	DISPATCH_LEVEL
DDI 규정 준수 규칙	IrqlDispatch(storport), IrqlDispatch(storport), IrqlDispatch(wdm)