共用方式為


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_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)

另請參閱

AddDevice

DEVICE_DESCRIPTION

DMA_ADAPTER

DMA_OPERATIONS

IRP_MN_START_DEVICE

PutDmaAdapter