Funzione IoGetDmaAdapter (wdm.h)

Articolo
03/08/2023

La routine IoGetDmaAdapter restituisce un puntatore alla struttura della scheda DMA per un oggetto dispositivo fisico.

Sintassi

_DMA_ADAPTER * IoGetDmaAdapter(
  [in, optional] PDEVICE_OBJECT      PhysicalDeviceObject,
  [in]           _DEVICE_DESCRIPTION *DeviceDescription,
  [out]          PULONG              NumberOfMapRegisters
);

Parametri

[in, optional] PhysicalDeviceObject

Puntatore all'oggetto dispositivo fisico per il dispositivo che richiede la struttura dell'adattatore DMA.

[in] DeviceDescription

Puntatore a una struttura DEVICE_DESCRIPTION , che descrive gli attributi del dispositivo fisico. Indipendentemente dalla versione impostata nella struttura DEVICE_DESCRIPTION, questa funzione restituisce DMA_ADAPTER->Version == 1sempre .

[out] NumberOfMapRegisters

Puntatore a, in output, numero massimo di registri mappa che il driver può allocare per qualsiasi operazione di trasferimento DMA.

Valore restituito

IoGetDmaAdapter restituisce un puntatore a una struttura DMA_ADAPTER , che contiene puntatori alle funzioni che supportano le operazioni DMA definite dal sistema. Se la struttura non può essere allocata, la routine restituisce NULL. Vedere il commento della versione precedente nella descrizione del parametro DeviceDescription .

Commenti

Prima di chiamare questa routine, un driver deve inizializzare zero la struttura DEVICE_DESCRIPTION puntata da DeviceDescription e quindi aggiungere le informazioni pertinenti per il dispositivo a questa struttura.

In caso di esito positivo, il valore restituito della routine punta a una struttura di DMA_ADAPTER . Questa struttura contiene un puntatore a una struttura DMA_OPERATIONS , ovvero una tabella di puntatori alle funzioni che il driver può usare successivamente per eseguire operazioni DMA. La versione di questa struttura restituita dalla routine viene determinata come segue:

Se il driver imposta il membro Version della struttura DEVICE_DESCRIPTION su DEVICE_DESCRIPTION_VERSION o DEVICE_DESCRIPTION_VERSION1, la struttura DMA_ADAPTER restituita punta alla versione 1 della struttura DMA_OPERATIONS .

Se il driver imposta Version = DEVICE_DESCRIPTION_VERSION2, la struttura DMA_ADAPTER restituita punta alla versione 2 della struttura DMA_OPERATIONS se è supportata la versione 2; in caso contrario, la routine restituisce NULL. I driver devono verificare se la versione 2 è supportata prima di provare a usare qualsiasi funzione versione 2.

Se il driver imposta Version = DEVICE_DESCRIPTION_VERSION3, la struttura DMA_ADAPTER restituita punta alla versione 3 della strutturaDMA_OPERATIONS se è supportata la versione 3; in caso contrario, la routine restituisce NULL. I driver devono verificare se la versione 3 è supportata prima di tentare di usare qualsiasi funzione versione 3. La versione 3 è supportata a partire da Windows 8.

Un driver PnP chiama IoGetDmaAdapter quando viene chiamata la routine AddDevice o quando gestisce una richiesta di IRP_MN_START_DEVICE PnP per un dispositivo. Questo IRP include informazioni sulle risorse hardware del dispositivo che il driver deve fornire nella struttura DeviceDescription .

Il chiamante usa il membro MaximumLength nella struttura DeviceDescription per indicare il numero ottimale di registri mappa che può usare. Il gestore di I/O tenterà di allocare registri mappa sufficienti per supportare un'operazione di trasferimento DMA di questa dimensione massima. Nell'output, la gestione I/O restituisce, nel parametro NumberOfMapRegisters , il numero di registri mappa allocati. I driver devono controllare il valore restituito; non esiste alcuna garanzia che un driver riceva lo stesso numero di registri mappa richiesti.

Per liberare l'oggetto adapter, il driver deve chiamare PutDmaAdapter tramite il puntatore restituito nella struttura DMA_ADAPTER .

Come descritto in precedenza, IoGetDmaAdapter restituisce NULL se non supporta la versione della struttura DMA_ADAPTER specificata da DeviceDescription-Version>. I chiamanti devono basarsi su questo comportamento per determinare se la routine restituisce un puntatore alla versione richiesta della struttura DMA_ADAPTER . Quando IoGetDmaAdapter restituisce un puntatore alla versione 1 o alla versione 2 o versione 3 della struttura DMA_ADAPTER , il membro Versione di questa struttura è sempre impostato su 1. Pertanto, il chiamante non può usare il membro Versiondella struttura DMA_ADAPTER restituita per distinguere tra le versioni 1, 2 e 3 di questa struttura.

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Intestazione	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Regole di conformità DDI	HwStorPortProhibitedDDDIs(storport), IrqlIoPassive5(wdm), PowerIrpDDis(wdm)