IoGetDmaAdapter 함수(wdm.h)
IoGetDmaAdapter 루틴은 물리적 디바이스 개체의 DMA 어댑터 구조에 대한 포인터를 반환합니다.
구문
_DMA_ADAPTER * IoGetDmaAdapter(
[in, optional] PDEVICE_OBJECT PhysicalDeviceObject,
[in] _DEVICE_DESCRIPTION *DeviceDescription,
[out] PULONG NumberOfMapRegisters
);
매개 변수
[in, optional] PhysicalDeviceObject
DMA 어댑터 구조를 요청하는 디바이스의 물리적 디바이스 개체에 대한 포인터입니다.
[in] DeviceDescription
물리적 디바이스의 특성을 설명하는 DEVICE_DESCRIPTION 구조체에 대한 포인터입니다. DEVICE_DESCRIPTION 구조에서 설정된 버전에 관계없이 이 함수는 항상 를 반환합니다 DMA_ADAPTER->Version == 1.
[out] NumberOfMapRegisters
출력 시 드라이버가 모든 DMA 전송 작업에 할당할 수 있는 최대 맵 레지스터 수에 대한 포인터입니다.
반환 값
IoGetDmaAdapter 는 시스템 정의 DMA 작업을 지원하는 함수에 대한 포인터를 포함하는 DMA_ADAPTER 구조체에 대한 포인터를 반환합니다. 구조를 할당할 수 없는 경우 루틴은 NULL을 반환합니다. DeviceDescription 매개 변수에 대한 설명은 위의 버전 주석을 참조하세요.
설명
이 루틴을 호출하기 전에 드라이버는 DeviceDescription이 가리키는 DEVICE_DESCRIPTION 구조를 0으로 초기화한 다음 해당 디바이스에 대한 관련 정보를 이 구조에 추가해야 합니다.
성공 시 루틴의 반환 값은 DMA_ADAPTER 구조를 가리킵니다. 이 구조체에는 드라이버가 이후에 DMA 작업을 수행하는 데 사용할 수 있는 함수에 대한 포인터 테이블인 DMA_OPERATIONS 구조체에 대한 포인터가 포함되어 있습니다. 루틴이 반환하는 이 구조체의 버전은 다음과 같이 결정됩니다.
드라이버가 DEVICE_DESCRIPTION 구조체의 Version 멤버를 DEVICE_DESCRIPTION_VERSION 또는 DEVICE_DESCRIPTION_VERSION1 설정하는 경우 반환된 DMA_ADAPTER 구조체는 DMA_OPERATIONS 구조체의 버전 1을 가리킵니다.
드라이버가 Version = DEVICE_DESCRIPTION_VERSION2 설정하는 경우 반환된 DMA_ADAPTER 구조체는 버전 2가 지원되는 경우 DMA_OPERATIONS 구조체의 버전 2를 가리킵니다. 그렇지 않으면 루틴은 NULL을 반환합니다. 드라이버는 버전 2 함수를 사용하기 전에 버전 2가 지원되는지 확인하기 위해 검사 합니다.
드라이버가 Version = DEVICE_DESCRIPTION_VERSION3 설정하는 경우 반환된 DMA_ADAPTER 구조체는 버전 3이 지원되는 경우 DMA_OPERATIONS 구조체의 버전 3을 가리킵니다. 그렇지 않으면 루틴은 NULL을 반환합니다. 드라이버는 버전 3 함수를 사용하기 전에 버전 3이 지원되는지 확인하기 위해 검사 합니다. 버전 3은 Windows 8 부터 지원됩니다.
PnP 드라이버는 AddDevice 루틴이 호출되거나 디바이스에 대한 PnP IRP_MN_START_DEVICE 요청을 처리할 때 IoGetDmaAdapter를 호출합니다. 이 IRP에는 드라이버가 DeviceDescription 구조에서 제공해야 하는 디바이스의 하드웨어 리소스에 대한 정보가 포함됩니다.
호출자는 DeviceDescription 구조에서 MaximumLength 멤버를 사용하여 사용할 수 있는 최적의 지도 레지스터 수를 나타냅니다. I/O 관리자는 이 최대 크기의 DMA 전송 작업을 수용하기 위해 충분한 맵 레지스터를 할당하려고 시도합니다. 출력 시 I/O 관리자는 NumberOfMapRegisters 매개 변수에서 할당하는 맵 레지스터 수를 반환합니다. 드라이버는 반환된 값을 검사 합니다. 드라이버가 요청한 것과 동일한 수의 지도 레지스터를 받게 된다는 보장은 없습니다.
어댑터 개체를 해제하려면 드라이버는 DMA_ADAPTER 구조에서 반환된 포인터를 통해 PutDmaAdapter를 호출해야 합니다.
앞에서 설명한 대로 IoGetDmaAdapter는 DeviceDescription-Version>으로 지정된 DMA_ADAPTER 구조체의 버전을 지원하지 않는 경우 NULL을 반환합니다. 호출자는 이 동작을 사용하여 루틴이 요청된 DMA_ADAPTER 구조체 버전에 대한 포인터를 반환하는지 여부를 결정해야 합니다. IoGetDmaAdapter가 DMA_ADAPTER 구조체의 버전 1 또는 버전 2 또는 버전 3에 대한 포인터를 반환하는 경우 이 구조체의 버전 멤버는 항상 1로 설정됩니다. 따라서 호출자는 반환된 DMA_ADAPTER 구조체의 Version 멤버를 사용하여 이 구조체의 버전 1, 2 및 3을 구분할 수 없습니다.
요구 사항
| 요구 사항 | 값 |
|---|---|
| 대상 플랫폼 | 유니버설 |
| 헤더 | wdm.h(Wdm.h, Ntddk.h, Ntifs.h 포함) |
| 라이브러리 | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| DDI 규정 준수 규칙 | HwStorPortProhibitedDDIs(storport), IrqlIoPassive5(wdm), PowerIrpDDis(wdm) |