IPortWavePciStream ::GetMapping, méthode (portcls.h)

Article
02/07/2025

La méthode GetMapping obtient un mappage à partir du pilote de port et associe une balise au mappage.

Syntaxe

NTSTATUS GetMapping(
  [in]  PVOID             Tag,
  [out] PPHYSICAL_ADDRESS PhysicalAddress,
  [out] PVOID             *VirtualAddress,
  [out] PULONG            ByteCount,
  [out] PULONG            Flags
);

Paramètres

[in] Tag

Spécifie une valeur d’étiquette à associer au mappage. Le pilote de port peut utiliser cette balise dans une IMiniportWavePciStream ::RevokeMappings appel pour identifier le mappage dans la liste des mappages à révoquer. Le pilote miniport utilise la balise pour identifier le mappage dans le IPortWavePciStream ::ReleaseMapping appel qui libère le mappage.

[out] PhysicalAddress

Pointeur de sortie pour l’adresse physique. Ce paramètre pointe vers une variable de pointeur allouée par l’appelant dans laquelle la méthode écrit l’adresse physique du mappage. Spécifiez une valeur de pointeur non NULL valide pour ce paramètre.

[out] VirtualAddress

Pointeur de sortie pour l’adresse virtuelle. Ce paramètre pointe vers une variable de pointeur allouée par l’appelant dans laquelle la méthode écrit l’adresse virtuelle du mappage. Spécifiez une valeur de pointeur non NULL valide pour ce paramètre.

[out] ByteCount

Pointeur de sortie pour le nombre d’octets. Ce paramètre pointe vers une variable ULONG allouée par l’appelant dans laquelle la méthode écrit le nombre d’octets dans le mappage. Spécifiez une valeur de pointeur non NULL valide pour ce paramètre.

[out] Flags

Pointeur de sortie pour l’indicateur d’état. Ce paramètre pointe vers une variable ULONG allouée par l’appelant dans laquelle la méthode écrit un indicateur d’état. Spécifiez une valeur de pointeur non NULL valide pour ce paramètre. Une valeur d’indicateur différente de zéro indique que le mappage acquis dans cet appel est le dernier mappage dans un paquet d’E/S. Cet indicateur peut être utilisé pour signaler que le matériel doit interrompre le pilote miniport lorsqu’il est effectué avec ce mappage. En réponse à l’interruption, le pilote miniport peut obtenir de nouveaux mappages à remettre au matériel. Le pilote miniport n’est pas obligé d’utiliser l’indicateur de cette façon.

Valeur de retour

GetMapping retourne STATUS_SUCCESS si l’appel a réussi. Sinon, la méthode retourne un code d’erreur approprié. Le tableau suivant présente certains des codes d’état de retour possibles.

Retourner le code	Description
STATUS_NOT_FOUND	Un mappage n’est pas immédiatement disponible, mais le pilote de port appelle IMiniportWavePciStream ::MappingAvailable lorsqu’un mappage devient disponible.

Remarques

Les mappages obtenus via la méthode GetMapping doivent être libérés en appelant IPortWavePciStream ::ReleaseMapping, sauf s’ils sont révoqués par le pilote de port. Le pilote de port peut révoquer des mappages en appelant la méthode IMiniportWavePciStream ::RevokeMappings du flux.

Le stockage de mémoire tampon pour un flux lu par le biais d’une broche de rendu du pilote miniport est attaché à un ou plusieurs IRPs. Chaque IRP contient une partie du stockage de mémoire tampon pour le flux. Le stockage de mémoire tampon de chaque IRP est contigu dans la mémoire virtuelle, mais les pages mémoire qui composent la mémoire tampon ne sont pas en général mappées aux emplacements contigus de la mémoire physique. Bien qu’un pilote puisse utiliser des E/S programmés pour accéder à la mémoire tampon via son mappage en mémoire virtuelle, un contrôleur DMA nécessite des mappages physiques à la place.

Le pilote de port WavePci utilise la méthode GetMapping pour exposer la mémoire tampon au pilote miniport comme séquence de mappages physiques. Un mappage classique est une page de mémoire ou moins de taille, bien qu’un mappage puisse dépasser la taille de la page si deux pages ou plus occupent des emplacements adjacents dans la mémoire physique.

L’appel initial à GetMapping génère le mappage au début de la mémoire tampon. Chaque appel successif à GetMapping présente le mappage séquentiel suivant dans la mémoire tampon. Après avoir atteint la fin de la mémoire tampon, l’appel suivant GetMapping génère le mappage au début de la mémoire tampon et la séquence de mappage se répète.

L’adresse de mémoire virtuelle en mode noyau du mappage est générée via le paramètre VirtualAddress. Le pilote miniport utilise cette adresse pour accéder au mappage sous contrôle de programme direct. La page qui contient le mappage est verrouillée et aucune erreur de page ne peut se produire lorsque le pilote accède au mappage. Le contrôleur DMA maître de bus de l’appareil audio utilise l’adresse qui est sortie via le paramètre PhysicalAddress pour accéder au mappage.

Le paramètre Tag est une valeur PVOID que l’appelant choisit d’identifier de manière unique le mappage :

Le pilote de port peut utiliser cette balise pour identifier le mappage dans un appel ultérieur à IMiniportWavePciStream ::RevokeMappings.
Le pilote miniport peut utiliser cette balise pour identifier le mappage dans un appel ultérieur à IPortWavePciStream ::ReleaseMapping.

Bien que balise soit définie comme étant de type PVOID, le pilote de port n’essaie jamais d’utiliser cette valeur comme pointeur et ne nécessite pas qu’il soit un pointeur valide.

Un pilote miniport WavePci classique conserve un enregistrement de chaque mappage qu’il reçoit. La balise peut être un pointeur vers un enregistrement ou un index dans un tableau d’enregistrements, par exemple, en fonction de l’implémentation. La seule condition requise pour une balise est qu’il s’agit d’une valeur pouvant être convertie en type PVOID.

Le paramètre Indicateurs indique si l’appel à GetMapping a récupéré le mappage final dans la partie de la mémoire tampon de données audio attachée à l’IRP de mappage actuel. Lorsque indicateurs indique qu’un mappage est le dernier mappage dans un IRP, un pilote miniport peut armer une interruption matérielle pour se déclencher lorsque le pilote miniport termine la lecture de ce mappage. Lorsque l’interruption se déclenche, cet événement informe le pilote miniport qu’il doit acquérir davantage de mappages à ajouter à sa file d’attente DMA. Le paramètre Flags est généralement utilisé par un pilote miniport qui gère un flux de lecture unique à partir du pilote système KMixer. KMixer utilise plusieurs irps de mappage (un minimum de trois dans l’implémentation actuelle de KMixer) pour mettre en mémoire tampon un seul flux de lecture. Par conséquent, si le pilote miniport génère une interruption matérielle chaque fois que le contrôleur DMA se termine avec le mappage final dans un IRP, les interruptions doivent se produire suffisamment fréquemment pour empêcher la file d’attente DMA de ne pas mourir.

Le paramètre indicateurs de est généralement ignoré par les pilotes miniport qui gèrent un ou plusieurs flux accélérés par le matériel DirectSound (voir Accélération matérielle DirectSound dans wdM Audio). Dans le cas d’une mémoire tampon DirectSound, la mémoire tampon entière peut être attachée à un seul IRP. Si la mémoire tampon est volumineuse et que le pilote miniport planifie une interruption matérielle uniquement lorsqu’il atteint la fin de la mémoire tampon, les interruptions se produisent jusqu’à présent que la file d’attente DMA risque de mourir de faim. En outre, si le pilote gère un grand nombre de flux, la planification d’une interruption matérielle chaque fois que les indicateurs de signalent une condition de mappage finale sur un flux peut générer tant d’interruptions que les performances peuvent être dégradées. Dans ces circonstances, le pilote miniport ne doit pas compter sur les interruptions matérielles pour acquérir des mappages. Au lieu de cela, il doit planifier les dpcs du minuteur à se produire à intervalles réguliers pour acquérir des mappages.

Un pilote miniport est le plus susceptible d’appeler GetMapping pendant un appel à l’objet de flux miniport SetState, Serviceou méthode MappingAvailable (voir IMiniportWavePciStream).

Pour éviter les blocages potentiels, le pilote de l’adaptateur doit éviter de conserver un verrou de rotation pendant son appel à GetMapping. Consultez l’exemple de pilote audio ac97 dans le Kit de pilotes Microsoft Windows (WDK) pour obtenir un exemple de code qui utilise un verrou de rotation pour sérialiser les accès aux structures de données partagées et aux périphériques dans un système multiprocesseur. L’exemple de code appelle KeReleaseSpinLock avant d’appeler GetMapping et appelle KeAcquireSpinLock après avoir appelé GetMapping. Entre les appels à libérer et acquérir le verrou de rotation, le thread de pilote ne doit pas supposer qu’il dispose d’un accès exclusif aux données ou périphériques qui sont gardés par le verrou de rotation. L’outil Driver Verifier vérifie les verrous de rotation actifs pendant les appels à GetMapping; s’il en détecte un, il génère une vérification des bogues 0xC4 (détection de blocage).

Bien que la taille d’un mappage classique soit une page de mémoire ou moins, un seul mappage peut dépasser la taille de la page si une partie d’une mémoire tampon audio se produit pour occuper deux pages contiguës ou plus dans la mémoire physique. Les mappages plus volumineux peuvent créer des problèmes pour le matériel DMA avec des défauts de conception qui limitent la taille du bloc. Par exemple, si un contrôleur DMA peut gérer une taille de bloc maximale d’une page unique et GetMapping génère un mappage supérieur à une page, le pilote miniport doit fractionner le mappage en blocs plus petits que le matériel DMA. Si le nombre de blocs résultant dépasse le nombre de registres cartographiques disponibles dans le matériel DMA, le pilote ne peut pas mettre en file d’attente tous les blocs dans une seule opération DMA de nuage de points/collecte. Lorsque cela se produit, le pilote doit suivre la partie non mise en file d’attente du mappage et lancer les transferts DMA des blocs restants ultérieurement lorsque des registres de carte supplémentaires deviennent disponibles.

Dans Windows 98/Me, Windows 2000, Windows XP et Windows Server 2003, la méthode GetMapping ne génère jamais de mappage qui s’étend sur plus de 16 pages. Cette limite peut changer dans les futures versions de Windows.

Pour plus d’informations sur les mappages, consultez de latence WavePci.