ioGetDmaAdapter 函式 (wdm.h)

發行項
02/27/2024

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_ADAPTER 結構的指標，其中包含支持系統定義 DMA 作業之函式的指標。如果無法配置結構，則例程會傳回 NULL。請參閱上述版本批注，以取得 DeviceDescription 參數的描述。

備註

呼叫此例程之前，驅動程式必須以零起始 DeviceDescription 指向的DEVICE_DESCRIPTION結構，然後將其裝置的相關信息新增至此結構。

成功時，例程的傳回值會指向 DMA_ADAPTER 結構。此結構包含 DMA_OPERATIONS 結構的指標，這是驅動程式後續可用來執行 DMA 作業之函式的指標數據表。例程所傳回的這個結構版本會依下列方式決定：

如果驅動程式將DEVICE_DESCRIPTION結構的 Version 成員設定為DEVICE_DESCRIPTION_VERSION或DEVICE_DESCRIPTION_VERSION1，則傳回的DMA_ADAPTER結構會指向DMA_OPERATIONS結構的第 1 版。

如果驅動程式設定 Version = DEVICE_DESCRIPTION_VERSION2，如果支援第 2 版，傳回 DMA_ADAPTER 結構會指向第 2 版 DMA_OPERATIONS 結構;否則，例程會傳回 NULL。驅動程式必須檢查是否支援第 2 版，才能嘗試使用任何第 2 版函式。

如果驅動程式設定 Version = DEVICE_DESCRIPTION_VERSION3，如果支援第 3 版，傳回 DMA_ADAPTER 結構會指向第 3 版 DMA_OPERATIONS 結構;否則，例程會傳回 NULL。驅動程式必須檢查是否支援第 3 版，才能嘗試使用任何第 3 版函式。從 Windows 8 開始，支援第3版。

當呼叫 PnP 驅動程式的 AddDevice 例程或處理裝置的 PnP IRP_MN_START_DEVICE要求時，PnP 驅動程式會呼叫 IoGetDmaAdapter。此 IRP 包含驅動程式必須在 DeviceDescription 結構中提供之裝置硬體資源的相關信息。

呼叫端會使用 DeviceDescription 結構中的 MaximumLength 成員，指出它可以使用的最佳地圖緩存器數目。 I/O 管理員會嘗試配置足夠的對應緩存器，以容納此大小上限的 DMA 傳輸作業。輸出時，I/O 管理員會在 NumberOfMapRegisters 參數中傳回它配置的對應緩存器數目。驅動程式應該檢查傳回的值;不保證驅動程式會收到所要求的相同地圖緩存器數目。

若要釋放配接器對象，驅動程式應該透過DMA_ADAPTER結構中傳回的指標呼叫 PutDmaAdapter。

如先前所述，如果 IoGetDmaAdapter 不支援 DeviceDescription-Version> 所指定的DMA_ADAPTER結構版本，IoGetDmaAdapter 會傳回 NULL。呼叫端應該依賴這個行為來判斷例程是否傳回所要求版本的 DMA_ADAPTER 結構的指標。當 IoGetDmaAdapter 傳回第 1 版或第 2 版或第 3 版DMA_ADAPTER結構的指標時，此結構的 Version 成員一律會設定為 1。因此，呼叫端無法使用所傳回之 DMA_ADAPTER 結構的 Version 成員來區分這個結構的版本 1、2 和 3。

規格需求

需求	值
目標平台	Universal
標頭	wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
程式庫	NtosKrnl.lib
Dll	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI 合規性規則	HwStorPortProhibitedDDIs (storport) 、 IrqlIoPassive5 (wdm) 、 PowerIrpDDis (wdm)