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

Article
02/27/2024

La GetMapping méthode 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 de balise à associer au mappage. Le pilote de port peut utiliser cette balise dans un appel suivant IMiniportWavePciStream ::RevokeMappings pour identifier le mappage dans la liste des mappages à révoquer. Le pilote miniport utilise la balise pour identifier le mappage dans l’appel IPortWavePciStream ::ReleaseMapping qui libère le mappage.

[out] PhysicalAddress

Pointeur de sortie pour l’adresse physique. Ce paramètre pointe vers une variable 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 status. Ce paramètre pointe vers une variable ULONG allouée par l’appelant dans laquelle la méthode écrit un indicateur status. 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 terminé avec ce mappage. En réponse à l’interruption, le pilote miniport peut obtenir de nouveaux mappages à livrer au matériel. Le pilote miniport n’est pas obligé d’utiliser le drapeau de cette façon.

Valeur retournée

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 de retour possibles status.

Code de retour	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 GetMapping méthode 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 les mappages en appelant la méthode IMiniportWavePciStream ::RevokeMappings du flux.

Le stockage de la mémoire tampon d’un flux lu via la broche de rendu d’un 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 la mémoire tampon de chaque IRP est contiguë dans la mémoire virtuelle, mais les pages de mémoire qui composent la mémoire tampon ne sont généralement pas mappées à des emplacements contigus dans la mémoire physique. Bien qu’un pilote puisse utiliser des E/S programmées pour accéder à la mémoire tampon via son mappage dans la mémoire virtuelle, un contrôleur DMA nécessite des mappages physiques à la place.

Le pilote de port WavePci utilise la GetMapping méthode pour exposer la mémoire tampon au pilote miniport en tant que séquence de mappages physiques. Un mappage classique est une page mémoire ou une taille inférieure, 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 master bus du périphérique 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 pour 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 Tag soit défini pour être de type PVOID, le pilote de port n’essaie jamais d’utiliser cette valeur comme pointeur et ne nécessite pas qu’il s’agisse d’un pointeur valide.

Un pilote de 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 exigence d’une balise est qu’il s’agit d’une valeur qui peut être convertie en type PVOID.

Le paramètre Flags indique si l’appel pour GetMapping récupérer le mappage final dans la partie de la mémoire tampon de données audio qui est attachée à l’IRP de mappage actuel. Lorsque flags indique qu’un mappage est le dernier mappage d’un IRP, un pilote miniport peut armer une interruption matérielle à déclencher lorsque le pilote miniport termine de jouer 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 IRP de mappage (au moins trois dans l’implémentation actuelle de KMixer) pour mettre en mémoire tampon un seul flux de lecture. Ainsi, si le pilote miniport génère une interruption matérielle chaque fois que le contrôleur DMA termine le mappage final dans un IRP, les interruptions doivent se produire suffisamment fréquemment pour empêcher la file d’attente DMA de s’affamer.

Le paramètre Flags est généralement ignoré par les pilotes miniport qui gèrent un ou plusieurs flux à accélération matérielle DirectSound (voir DirectSound Hardware Acceleration in 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’elle atteint la fin de la mémoire tampon, les interruptions se produisent si loin 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 le paramètre Flags signale une condition de mappage finale sur un flux peut générer tellement d’interruptions que les performances peuvent être dégradées. Dans ces circonstances, le pilote miniport ne doit pas compter sur des interruptions matérielles pour acquérir des mappages. Au lieu de cela, il doit planifier les DPC du minuteur pour qu’ils se produisent à intervalles réguliers pour acquérir des mappages.

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

Pour éviter les interblocages potentiels, le pilote de l’adaptateur doit éviter de maintenir 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 l’appel GetMappingde . 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 aux périphériques qui sont gardés par le verrou de rotation. L’outil Vérificateur de pilotes recherche les verrous de rotation actifs pendant les appels à GetMapping; s’il en détecte un, il génère un bogue 0xC4 (détection d’interblocage) case activée.

Bien que la taille d’un mappage classique soit d’une page mémoire ou moins, un seul mappage peut dépasser la taille de la page si une partie d’une mémoire tampon audio occupe 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 seule page 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 peut gérer. 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 diffusion/collecte. Lorsque cela se produit, le pilote doit effectuer le suivi de la partie non mise en file d’attente du mappage et lancer des transferts DMA des blocs restants ultérieurement lorsque des registres cartographiques supplémentaires sont disponibles.

Dans Windows 98/Me, Windows 2000, Windows XP et Windows Server 2003, la GetMapping méthode 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 Latence de WavePci.