Fonction IoGetDmaAdapter (wdm.h)

Article
02/27/2024

La routine IoGetDmaAdapter retourne un pointeur vers la structure de l’adaptateur DMA pour un objet d’appareil physique.

Syntaxe

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

Paramètres

[in, optional] PhysicalDeviceObject

Pointeur vers l’objet d’appareil physique pour l’appareil demandant la structure de l’adaptateur DMA.

[in] DeviceDescription

Pointeur vers une structure DEVICE_DESCRIPTION , qui décrit les attributs de l’appareil physique. Quelle que soit la version définie dans la structure DEVICE_DESCRIPTION, cette fonction retourne DMA_ADAPTER->Version == 1toujours .

[out] NumberOfMapRegisters

Pointeur vers, lors de la sortie, le nombre maximal de registres de carte que le pilote peut allouer à n’importe quelle opération de transfert DMA.

Valeur retournée

IoGetDmaAdapter retourne un pointeur vers une structure DMA_ADAPTER , qui contient des pointeurs vers des fonctions qui prennent en charge les opérations DMA définies par le système. Si la structure ne peut pas être allouée, la routine retourne NULL. Consultez le commentaire de version ci-dessus dans la description du paramètre DeviceDescription .

Remarques

Avant d’appeler cette routine, un pilote doit initialiser zéro la structure DEVICE_DESCRIPTION pointée par DeviceDescription , puis ajouter les informations pertinentes pour son appareil à cette structure.

En cas de réussite, la valeur de retour de la routine pointe vers une structure DMA_ADAPTER . Cette structure contient un pointeur vers une structure DMA_OPERATIONS , qui est une table de pointeurs vers des fonctions que le pilote peut ensuite utiliser pour effectuer des opérations DMA. La version de cette structure retournée par la routine est déterminée comme suit :

Si le pilote définit le membre Version de la structure DEVICE_DESCRIPTION sur DEVICE_DESCRIPTION_VERSION ou DEVICE_DESCRIPTION_VERSION1, la structure DMA_ADAPTER retournée pointe vers la version 1 de la structure DMA_OPERATIONS .

Si le pilote définit Version = DEVICE_DESCRIPTION_VERSION2, la structure DMA_ADAPTER retournée pointe vers la version 2 de la structure DMA_OPERATIONS si la version 2 est prise en charge ; sinon, la routine retourne NULL. Les pilotes doivent case activée pour voir si la version 2 est prise en charge avant d’essayer d’utiliser une fonction de version 2.

Si le pilote définit Version = DEVICE_DESCRIPTION_VERSION3, la structure DMA_ADAPTER retournée pointe vers la version 3 de la structure DMA_OPERATIONS si la version 3 est prise en charge ; sinon, la routine retourne NULL. Les pilotes doivent case activée pour voir si la version 3 est prise en charge avant d’essayer d’utiliser une fonction version 3. La version 3 est prise en charge à partir de Windows 8.

Un pilote PnP appelle IoGetDmaAdapter quand sa routine AddDevice est appelée ou lorsqu’il gère une demande de IRP_MN_START_DEVICE PnP pour un appareil. Cette IRP inclut des informations sur les ressources matérielles de l’appareil que le pilote doit fournir dans la structure DeviceDescription .

L’appelant utilise le membre MaximumLength dans la structure DeviceDescription pour indiquer le nombre optimal de registres de carte qu’il peut utiliser. Le gestionnaire d’E/S tente d’allouer suffisamment de registres de carte pour prendre en charge une opération de transfert DMA de cette taille maximale. À la sortie, le gestionnaire d’E/S retourne, dans le paramètre NumberOfMapRegisters , le nombre de registres de carte qu’il alloue. Les pilotes doivent case activée la valeur retournée ; il n’existe aucune garantie qu’un pilote recevra le même nombre de registres cartographiques qu’il a demandé.

Pour libérer l’objet adaptateur, le pilote doit appeler PutDmaAdapter via le pointeur retourné dans la structure DMA_ADAPTER .

Comme décrit précédemment, IoGetDmaAdapter retourne NULL s’il ne prend pas en charge la version de la structure DMA_ADAPTER spécifiée par DeviceDescription-Version>. Les appelants doivent s’appuyer sur ce comportement pour déterminer si la routine retourne un pointeur vers la version demandée de la structure DMA_ADAPTER . Quand IoGetDmaAdapter retourne un pointeur vers la version 1, la version 2 ou la version 3 de la structure DMA_ADAPTER , le membre Version de cette structure est toujours défini sur 1. Par conséquent, l’appelant ne peut pas utiliser le membre Version de la structure DMA_ADAPTER retournée pour faire la distinction entre les versions 1, 2 et 3 de cette structure.

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
En-tête	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Règles de conformité DDI	HwStorPortProhibitedDDIs(storport), IrqlIoPassive5(wdm), PowerIrpDDis(wdm)