PALLOCATE_ADAPTER_CHANNEL_EX 콜백 함수(wdm.h)

아티클
03/08/2023

AllocateAdapterChannelEx 루틴은 DMA 전송을 수행하는 데 필요한 리소스를 할당한 다음 드라이버 제공 AdapterControl 루틴을 호출하여 DMA 전송을 시작합니다.

구문

PALLOCATE_ADAPTER_CHANNEL_EX PallocateAdapterChannelEx;

NTSTATUS PallocateAdapterChannelEx(
  [in]            PDMA_ADAPTER DmaAdapter,
  [in]            PDEVICE_OBJECT DeviceObject,
  [in]            PVOID DmaTransferContext,
  [in]            ULONG NumberOfMapRegisters,
  [in]            ULONG Flags,
  [in, optional]  PDRIVER_CONTROL ExecutionRoutine,
  [in, optional]  PVOID ExecutionContext,
  [out, optional] PVOID *MapRegisterBase
)
{...}

매개 변수

[in] DmaAdapter

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

[in] DeviceObject

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

[in] DmaTransferContext

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

[in] NumberOfMapRegisters

DMA 전송에 사용할 지도 레지스터의 수입니다. 호출 드라이버는 현재 전송 요청을 충족하는 데 필요한 맵 레지스터 수와 사용 가능한 맵 레지스터 수보다 작은 값으로 설정해야 합니다. 이전에 드라이버는 전송에 필요한 맵 레지스터 수를 얻기 위해 GetDmaTransferInfo 루틴을 호출하고 IoGetDmaAdapter 루틴을 호출하여 사용 가능한 맵 레지스터 수를 얻었습니다.

[in] Flags

어댑터 채널 할당 플래그입니다. 다음 플래그가 지원됩니다.

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

DMA_SYNCHRONOUS_CALLBACK 플래그가 설정된 경우 ExecutionRoutine 매개 변수는 선택 사항이며 NULL일 수 있습니다. 이 플래그에 대한 자세한 내용은 설명 섹션을 참조하세요.

[in, optional] ExecutionRoutine

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

DMA_SYNCHRONOUS_CALLBACK 플래그가 설정된 경우 ExecutionRoutine은 선택 사항이며 NULL일 수 있습니다. 이 경우 호출자는 AllocateAdapterChannelEx에서 할당한 리소스를 사용하고 나중에 FreeAdapterObject 루틴을 호출하여 이러한 리소스를 해제할 수 있습니다. 자세한 내용은 주의 섹션을 참조하세요.

[in, optional] ExecutionContext

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

[out, optional] MapRegisterBase

루틴이 할당된 맵 레지스터에 핸들을 쓰는 변수에 대한 포인터입니다. 호출자는 이 핸들을 FlushAdapterBuffersEx, FlushAdapterBuffers, FreeMapRegisters 또는 MapTransferEx 루틴에 매개 변수로 제공할 수 있습니다.

DMA_SYNCHRONOUS_CALLBACK 플래그가 설정된 경우 MapRegisterBase는 NULL이 아닌 유효한 포인터여야 합니다. ExecutionRoutine 매개 변수가 NULL이 아닌 경우 MapRegisterBase는 NULL이어야 합니다. MapRegisterBase가 NULL이 아니고 DMA_SYNCHRONOUS_CALLBACK 플래그가 설정되지 않았거나 MapRegisterBase 및 ExecutionRoutine이 모두 NULL인 경우 호출이 실패합니다.

반환 값

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

반환 코드	설명
STATUS_INVALID_PARAMETERS	호출자가 전달한 잘못된 매개 변수 값으로 인해 루틴이 실패했습니다.
STATUS_INSUFFICIENT_RESOURCES	루틴이 DMA 전송에 필요한 리소스를 할당하지 못했습니다.

설명

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

AllocateAdapterChannelEx 는 DMA 작업을 수행하는 데 필요한 리소스를 할당합니다. 이러한 리소스에는 DMA 채널 및 지도 레지스터가 포함됩니다. DMA 어댑터에서 사용하기 위해 필요한 모든 리소스를 할당한 후 AllocateAdapterChannelEx 는 호출자가 제공한 AdapterControl 루틴을 호출하여 DMA 작업을 시작합니다.

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

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

요청된 DMA 리소스를 즉시 사용할 수 없는 경우 AllocateAdapterChannelEx 는 리소스를 기다리지 않고 AdapterControl 루틴을 호출하지 않습니다. 대신 AllocateAdapterChannelEx 가 실패하고 STATUS_INSUFFICIENT_RESOURCES 반환합니다.
DMA_SYNCHRONOUS_CALLBACK 플래그가 설정된 경우 드라이버는 AdapterControl 루틴을 제공할 필요가 없습니다.
드라이버가 AdapterControl 루틴을 제공하는 경우 DMA_SYNCHRONOUS_CALLBACK 플래그는 AllocateAdapterChannelEx 가 반환되기 전에 호출 스레드의 컨텍스트에서 이 루틴을 호출해야 했음을 나타냅니다.
드라이버가 AdapterControl 루틴을 제공하지 않으면 AllocateAdapterChannelEx 가 반환된 후 드라이버가 할당된 리소스를 사용할 수 있습니다. 이 경우 드라이버는 할당된 리소스 사용을 완료한 후 FreeAdapterObject 를 호출해야 합니다.

AllocateAdapterChannelEx 는 AllocateAdapterChannel 루틴의 확장 버전입니다. 다음 기능은 확장 버전에서만 사용할 수 있습니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 8 사용하여 사용할 수 있습니다.
대상 플랫폼	데스크톱
헤더	wdm.h(Wdm.h, Ntddk.h, Ntifs.h 포함)
IRQL	DISPATCH_LEVEL