structure DEVICE_DESCRIPTION (wdm.h)

Article
08/08/2023

La structure DEVICE_DESCRIPTION décrit les attributs de l’appareil physique pour lequel un pilote demande une carte DMA.

Syntaxe

typedef struct _DEVICE_DESCRIPTION {
  ULONG            Version;
  BOOLEAN          Master;
  BOOLEAN          ScatterGather;
  BOOLEAN          DemandMode;
  BOOLEAN          AutoInitialize;
  BOOLEAN          Dma32BitAddresses;
  BOOLEAN          IgnoreCount;
  BOOLEAN          Reserved1;
  BOOLEAN          Dma64BitAddresses;
  ULONG            BusNumber;
  ULONG            DmaChannel;
  INTERFACE_TYPE   InterfaceType;
  DMA_WIDTH        DmaWidth;
  DMA_SPEED        DmaSpeed;
  ULONG            MaximumLength;
  ULONG            DmaPort;
  ULONG            DmaAddressWidth;
  ULONG            DmaControllerInstance;
  ULONG            DmaRequestLine;
  PHYSICAL_ADDRESS DeviceAddress;
} DEVICE_DESCRIPTION, *PDEVICE_DESCRIPTION;

Membres

Version

Version de cette structure. Le membre Version de la structure DEVICE_DESCRIPTION passée à la routine IoGetDmaAdapter détermine quelle version de la structure DMA_ADAPTER est retournée par cette routine. Voici la liste des valeurs possibles du membre Version et des versions DMA_ADAPTER correspondantes :

DEVICE_DESCRIPTION_VERSION

Si version = DEVICE_DESCRIPTION_VERSION, IoGetDmaAdapter ignore le membre IgnoreCount et retourne la version 1 de la structure DMA_ADAPTER .

DEVICE_DESCRIPTION_VERSION1

Si version = DEVICE_DESCRIPTION_VERSION1, IoGetDmaAdapter utilise le membre IgnoreCount et retourne la version 1 de la structure DMA_ADAPTER .

DEVICE_DESCRIPTION_VERSION2

Si version = DEVICE_DESCRIPTION_VERSION2, IoGetDmaAdapter utilise le membre IgnoreCount et retourne la version 2 de la structure DMA_ADAPTER . La version 2 est disponible à partir de Windows XP.

DEVICE_DESCRIPTION_VERSION3

Si version = DEVICE_DESCRIPTION_VERSION3, IoGetDmaAdapter utilise le membre IgnoreCount et retourne la version 3 de la structure DMA_ADAPTER . La version 3 est disponible à partir de Windows 8.

Master

Indique si l’appareil est un appareil DMA master bus. Définissez sur TRUE si l’appareil est un appareil DMA master bus. Définissez sur FALSE s’il s’agit d’un appareil DMA subordonné.

ScatterGather

Pour un appareil DMA master bus, ce membre indique si l’appareil prend en charge la diffusion/la collecte DMA. Définissez sur TRUE si l’appareil peut effectuer des tâches de diffusion/collecte de données DMA. Sinon, définissez ce membre sur FALSE.

Pour un appareil DMA subordonné, la valeur ScatterGather n’est pas utilisée. Au lieu de cela, IoGetDmaAdapter suppose que la capacité de diffusion/collecte d’un appareil DMA subordonné est identique à celle du contrôleur DMA système sous-jacent auquel l’appareil est connecté.

DemandMode

Ce membre est utilisé uniquement si Version est DEVICE_DESCRIPTION_VERSION2.

Pour un appareil DMA subordonné, ce membre indique s’il faut utiliser le mode de demande du contrôleur DMA système. Définissez sur TRUE pour utiliser le mode de demande. Sinon, définissez ce membre sur FALSE.

Pour un appareil DMA master bus, la valeur DemandMode n’est pas utilisée.

Si Version est DEVICE_DESCRIPTION_VERSION, DEVICE_DESCRIPTION_VERSION1 ou DEVICE_DESCRIPTION_VERSION3, la valeur DemandMode n’est pas utilisée.

AutoInitialize

Pour un appareil DMA subordonné, ce membre indique s’il faut utiliser le mode d’ininitialisation automatique du contrôleur DMA système. Définissez sur TRUE pour utiliser le mode d’initialisation automatique. Sinon, définissez ce membre sur FALSE.

Pour un appareil DMA master bus, la valeur AutoInitialize n’est pas utilisée.

Dma32BitAddresses

Ce membre est utilisé uniquement si Version est DEVICE_DESCRIPTION_VERSION, DEVICE_DESCRIPTION_VERSION1 ou DEVICE_DESCRIPTION_VERSION2.

Dma32BitAddresses spécifie si l’appareil peut utiliser des adresses 32 bits complètes pour les opérations DMA. Définissez sur TRUE si l’appareil prend en charge les adresses 32 bits. Sinon, définissez ce membre sur FALSE.

Si Version = DEVICE_DESCRIPTION_VERSION3, la valeur Dma32BitAddresses n’est pas utilisée.

IgnoreCount

Indique s’il faut ignorer le compteur de transfert du contrôleur DMA. Défini sur TRUE si le contrôleur DMA de cette plateforme ne gère pas de compteur de transfert précis et nécessite donc une solution de contournement. Sinon, définissez ce membre sur FALSE.

Si Version = DEVICE_DESCRIPTION_VERSION, la valeur IgnoreCount n’est pas utilisée.

Pour plus d'informations, consultez la section Notes.

Reserved1

Réservé pour le système. Doit être FALSE.

Dma64BitAddresses

Ce membre est utilisé uniquement si Version est DEVICE_DESCRIPTION_VERSION, DEVICE_DESCRIPTION_VERSION1 ou DEVICE_DESCRIPTION_VERSION2.

Dma64BitAddresses spécifie si l’appareil peut utiliser des adresses 64 bits complètes pour les opérations DMA. Définissez sur TRUE si l’appareil prend en charge les adresses 64 bits. Sinon, définissez ce membre sur FALSE.

Si Version = DEVICE_DESCRIPTION_VERSION3, la valeur Dma64BitAddresses n’est pas utilisée.

BusNumber

Numéro de bus attribué par le système pour le bus d’E/S. Ce membre n’est pas utilisé par les pilotes WDM.

DmaChannel

Numéro du canal DMA auquel un appareil subordonné est affecté. Le pilote de périphérique obtient ce numéro de canal à partir de la liste de ressources qu’il reçoit dans la requête IRP_MN_START_DEVICE qui démarre l’appareil. Pour plus d’informations sur ce nombre, consultez la description du membre Dma.Channel dans CM_PARTIAL_RESOURCE_DESCRIPTOR.

InterfaceType

Type d’interface du bus d’E/S à utiliser pour DMA. Définissez ce membre sur la valeur d’énumération INTERFACE_TYPE qui indique le type d’interface. Pour plus d'informations, consultez la section Notes.

DmaWidth

Pour un appareil DMA subordonné, ce membre spécifie la largeur des données DMA pour les transferts par le contrôleur DMA système. Les valeurs possibles sont Width8Bits, Width16Bits, Width32Bits et Width64Bits.

Pour un appareil DMA master bus, la valeur DmaWidth n’est pas utilisée.

DmaSpeed

Ce membre est utilisé uniquement si Version est DEVICE_DESCRIPTION_VERSION, DEVICE_DESCRIPTION_VERSION1 ou DEVICE_DESCRIPTION_VERSION2.

Pour un appareil DMA subordonné, ce membre spécifie l’une des vitesses suivantes pour la DMA système : Compatible, TypeA, TypeB, TypeC ou TypeF.

Pour un appareil DMA master bus, la valeur DmaSpeed n’est pas utilisée.

Si Version = DEVICE_DESCRIPTION_VERSION3, la valeur DmaSpeed n’est pas utilisée.

MaximumLength

Nombre maximal d’octets que l’appareil peut transférer dans une opération DMA qui utilise l’objet d’adaptateur alloué.

DmaPort

Numéro de port de bus de type microcanal. Ce paramètre est obsolète, mais il est conservé dans la structure à des fins de compatibilité avec les pilotes hérités.

DmaAddressWidth

Ce membre est utilisé uniquement si Version = DEVICE_DESCRIPTION_VERSION3.

Pour un appareil DMA master bus, DmaAddressWidth spécifie la largeur, en bits, d’une adresse DMA. La valeur DmaAddressWidth doit être différente de zéro et ne doit pas dépasser 64. Si la largeur de l’adresse mémoire est supérieure à la largeur de l’adresse DMA, des registres de carte sont nécessaires pour accéder à une région de mémoire qui est au-delà de la portée d’adresse du contrôleur DMA.

Pour un appareil DMA subordonné, la valeur DmaAddressWidth n’est pas utilisée. Au lieu de cela, IoGetDmaAdapter suppose que la largeur d’adresse d’un appareil DMA subordonné est identique à celle du contrôleur DMA système sous-jacent auquel l’appareil est connecté.

DmaControllerInstance

Non utilisé.

DmaRequestLine

Ce membre est utilisé uniquement si Version = DEVICE_DESCRIPTION_VERSION3.

Pour un appareil DMA subordonné, DmaRequestLine spécifie la ligne de requête sur le contrôleur DMA auquel l’appareil est connecté. Le pilote de périphérique obtient le numéro de cette ligne de requête à partir de la liste de ressources qu’il reçoit dans la IRP_MN_START_DEVICE demande qui démarre l’appareil. Pour plus d’informations sur le numéro de ligne de requête, consultez la description du membre u.DmaV3.RequestLine dans CM_PARTIAL_RESOURCE_DESCRIPTOR.

Pour un appareil DMA master bus, la valeur DmaRequestLine n’est pas utilisée.

DeviceAddress

Ce membre est utilisé uniquement si Version = DEVICE_DESCRIPTION_VERSION3.

Pour un appareil DMA subordonné, DeviceAddress est l’adresse mappée en mémoire du registre de données sur l’appareil utilisé comme source ou destination pour un transfert DMA. Ce registre de données se trouve à un décalage connu, spécifique à l’appareil, de l’adresse de démarrage de l’appareil. La largeur de ce registre est spécifiée par le membre DmaWidth . Le pilote de périphérique obtient l’adresse de démarrage de l’appareil à partir de la liste de ressources qu’il reçoit dans la demande IRP_MN_START_DEVICE qui démarre l’appareil. Pour plus d’informations sur cette adresse, consultez la description du membre u.Memory.Start dans CM_PARTIAL_RESOURCE_DESCRIPTOR.

Pour un appareil DMA master bus, le membre DeviceAddress n’est pas utilisé.

Remarques

Le pilote d’un appareil qui utilise DMA pour transférer des données utilise la structure DEVICE_DESCRIPTION pour transmettre des informations sur l’appareil à la routine IoGetDmaAdapter . Le pilote appelle cette routine pour demander un objet adaptateur pour un objet de périphérique physique (PDO). Ce PDO représente la connexion physique de l’appareil au bus d’E/S à utiliser pour DMA. Pour plus d’informations, consultez Obtention d’un objet Adapter.

Pour allouer des ressources pour un contrôleur DMA, le gestionnaire d’E/S a besoin d’informations sur le contrôleur, mais peut obtenir certaines de ces informations uniquement à partir d’un pilote. Par exemple, le pilote d’un appareil master de bus sait si l’appareil prend en charge la diffusion/collecte DMA ou utilise des adresses 32 bits complètes. Ou bien, le pilote d’un appareil subordonné peut déterminer le numéro de canal DMA à partir de la liste de ressources que le pilote reçoit dans la demande IRP_MN_START_DEVICE qui démarre l’appareil. Le pilote utilise la structure DEVICE_DESCRIPTION pour transmettre ces informations au gestionnaire d’E/S.

Avant d’appeler IoGetDmaAdapter, le pilote doit d’abord zéro initialiser l’ensemble de la structure DEVICE_DESCRIPTION , puis remplir les membres sélectionnés pour décrire l’appareil.

Le membre InterfaceType spécifie le type d’interface de bus qui sera utilisé pour DMA. Si vous définissez InterfaceType sur InterfaceTypeUndefined, IoGetDmaAdapter interroge le PDO pour déterminer le type d’interface approprié pour votre appareil. Vous pouvez également spécifier un type d’interface explicite, tel que Internal, Isa, Eisa ou PCIBus. Pour plus d’informations, consultez la liste des types d’interface pris en charge dans INTERFACE_TYPE.

Si le membre ScatterGather a la valeur TRUE et que le membre InterfaceType est défini sur PCIBus, le membre Dma32BitAddresses est ignoré et IoGetDmaAdapter suppose que l’appareil prend en charge les adresses DMA 32 bits.

Si le membre Dma64BitAddresses a la valeur TRUE, le membre Dma32BitAddresses est ignoré et IoGetDmaAdapter suppose que l’appareil prend en charge les adresses DMA 64 bits.

Pour indiquer que le matériel du contrôleur DMA ne peut pas maintenir de manière fiable un nombre de transferts précis, définissez IgnoreCount sur TRUE et définissez Version sur une valeur autre que DEVICE_DESCRIPTION_VERSION. Dans une plateforme qui dispose d’un tel contrôleur DMA, le système d’exploitation ignore le compteur de transfert DMA, mais doit prendre des précautions particulières pour maintenir l’intégrité des données pendant les opérations DMA. En règle générale, l’utilisation d’une solution de contournement pour compenser un contrôleur DMA déficient dégrade la vitesse des transferts DMA.

Un pilote doit spécifier TypeF comme valeur DmaSpeed uniquement si le microprogramme ACPI de l’ordinateur le prend en charge.