Fonction IoGetDmaAdapter (wdm.h)
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 de 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 toujours DMA_ADAPTER->Version == 1.
[out] NumberOfMapRegisters
Pointeur vers, en sortie, le nombre maximal de registres cartographiques que le pilote peut allouer pour n’importe quelle opération de transfert DMA.
Valeur de retour
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 de paramètre DeviceDescription.
Remarques
Avant d’appeler cette routine, un pilote doit initialiser 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 vérifier si la version 2 est prise en charge avant de tenter d’utiliser une fonction 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 vérifier si la version 3 est prise en charge avant de tenter d’utiliser une fonction version 3. La version 3 est prise en charge à partir de Windows 8.
Un pilote PnP appelle IoGetDmaAdapter lorsque sa routine AddDevice est appelée ou lorsqu’elle gère une demande de IRP_MN_START_DEVICE PnP pour un appareil. Cet 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 cartographiques qu’il peut utiliser. Le gestionnaire d’E/S tente d’allouer suffisamment de registres cartographiques pour prendre en charge une opération de transfert DMA de cette taille maximale. En sortie, le gestionnaire d’E/S retourne, dans le paramètre NumberOfMapRegisters, le nombre de registres de carte qu’il alloue. Les pilotes doivent vérifier la valeur retournée ; il n’y a aucune garantie qu’un pilote recevra le même nombre de registres cartographiques qu’il a demandés.
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. Lorsque IoGetDmaAdapter retourne un pointeur vers la version 1 ou la version 2 ou la version 3 de la structure DMA_ADAPTER, le membre version de cette structure est toujours défini sur 1. Ainsi, l’appelant ne peut pas utiliser le membre version de la structure de DMA_ADAPTER retournée pour faire la distinction entre les versions 1, 2 et 3 de cette structure.
Exigences
| Exigence | Valeur |
|---|---|
| plateforme cible | Universel |
| d’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) |