PSETUP_DMA_ENGINE_WITH_BDL fonction de rappel (hdaudio.h)

Article
07/27/2023

La routine SetupDmaEngineWithBdl configure un moteur DMA pour utiliser une mémoire tampon DMA allouée à l’appelant.

Le type de pointeur de fonction pour une routine SetupDmaEngineWithBdl est défini comme suit.

Syntaxe

PSETUP_DMA_ENGINE_WITH_BDL PsetupDmaEngineWithBdl;

NTSTATUS PsetupDmaEngineWithBdl(
  [in]  PVOID _context,
  [in]  HANDLE Handle,
  [in]  ULONG BufferLength,
  [in]  ULONG Lvi,
  [in]  PHDAUDIO_BDL_ISR Isr,
  [in]  PVOID Context,
  [out] PUCHAR StreamId,
  [out] PULONG FifoSize
)
{...}

Paramètres

[in] _context

Spécifie la valeur de contexte du membre Context de la structure HDAUDIO_BUS_INTERFACE_BDL .

[in] Handle

Handle qui identifie le moteur DMA. Cette valeur de handle a été obtenue à partir d’un appel précédent à AllocateCaptureDmaEngine ou AllocateRenderDmaEngine.

[in] BufferLength

Longueur de la mémoire tampon.

[in] Lvi

Spécifie le dernier index valide (LVI). Ce paramètre contient l’index du dernier descripteur de mémoire tampon valide dans le BDL. Une fois que le moteur DMA a traité ce descripteur, il retourne au premier descripteur de la liste et continue le traitement. Si le BDL contient n descripteurs, ils sont numérotés de 0 à n-1. La valeur lvi doit être au moins égale à 1 ; en d’autres termes, le fichier BDL doit contenir au moins deux entrées valides pour que le moteur DMA puisse commencer à fonctionner.

[in] Isr

Pointeur de fonction vers l’ISR de l’appelant. Si l’appelant définit le bit d’interruption lors de l’achèvement (IOC) dans un ou plusieurs des descripteurs de mémoire tampon dans le BDL, le pilote de bus AUDIO HD appelle l’ISR chaque fois qu’une interruption IOC se produit sur le flux. Ce paramètre est un pointeur de fonction de type HDAUDIO_BDL_ISR, qui est défini dans la section Notes suivante.

[in] Context

Contexte.

[out] StreamId

Récupère l’identificateur de flux. Ce paramètre pointe vers une variable UCHAR allouée à l’appelant dans laquelle la routine écrit l’identificateur de flux qu’elle affecte au flux.

[out] FifoSize

Récupère la taille FIFO du moteur DMA en octets. Ce paramètre pointe vers une variable UINT allouée par l’appelant dans laquelle la routine écrit la taille FIFO.

Valeur retournée

SetupDmaEngineWithBdl retourne STATUS_SUCCESS si l’appel réussit. Sinon, la routine retourne un code d’erreur approprié. Le tableau suivant présente certains des codes de retour possibles status.

Code de retour	Description
STATUS_UNSUCCESSFUL	Indique que l’appelant s’exécute sur un IRQL trop élevé.
STATUS_INVALID_HANDLE	Indique que la valeur du paramètre handle n’est pas valide.
STATUS_INVALID_PARAMETER	Indique que l’une des valeurs de paramètre est incorrecte (pointeur incorrect ou format de flux non valide).
STATUS_DEVICE_NOT_READY	Indique que la programmation matérielle a expiré. Si cela se produit, le matériel peut être dans un état compromis.
STATUS_INVALID_DEVICE_REQUEST	Indique que l’appareil DMA ou la mémoire tampon DMA n’est pas alloué ou que le flux n’est pas dans l’état Réinitialiser.

Remarques

La routine SetupDmaEngineWithBdl est utilisée conjointement avec les routines AllocateContiguousDmaBuffer et FreeContiguousDmaBuffer . Ces trois routines sont disponibles uniquement dans la version HDAUDIO_BUS_INTERFACE_BDL de hd Audio DDI. Cette DDI n’inclut pas les routines AllocateDmaBuffer et FreeDmaBuffer , qui ne sont jamais utilisées conjointement avec AllocateContiguousDmaBuffer, SetupDmaEngineWithBdl et FreeContiguousDmaBuffer. Contrairement à SetupDmaEngineWithBdl, qui configure le moteur DMA pour utiliser une mémoire tampon DMA précédemment allouée, AllocateDmaBuffer alloue à la fois une mémoire tampon DMA et configure le moteur DMA pour utiliser la mémoire tampon.

L’appelant doit appeler AllocateContiguousDmaBuffer pour allouer du stockage dans la mémoire système à la fois pour la mémoire tampon DMA et la bibliothèque BDL qui décrit les pages de mémoire physique dans la mémoire tampon. Les entrées BDL doivent résider dans la mémoire qui est physiquement contiguë. La mémoire BDL et la mémoire tampon doivent répondre aux exigences d’alignement décrites dans la spécification audio Haute Définition Intel (voir le site web d’Intel HD Audio ).

La mémoire BDL et la mémoire tampon qu’il décrit doivent rester valides pendant les opérations DMA. Après l’appel à SetupDmaEngineWithBdl, le BDL et la mémoire tampon doivent rester valides tant que le moteur DMA continue à utiliser la mémoire tampon. Le moteur DMA utilise la mémoire tampon jusqu’à ce que le pilote de fonction remplace la mémoire tampon en appelant à nouveau SetupDmaEngineWithBdl ou libère le moteur DMA en appelant FreeDmaEngine. Le pilote de fonction est chargé d’appeler FreeContiguousDmaBuffer pour libérer la mémoire tampon et BDL lorsqu’ils ne sont plus nécessaires.

Lors de l’allocation de mémoire pour la mémoire tampon, l’appelant doit satisfaire toutes les contraintes matérielles pour l’adresse, la longueur et l’alignement des blocs de mémoire physiquement contigus spécifiés par le BDL. Par conséquent, seuls les clients ayant une connaissance significative du contrôleur de bus et du matériel système doivent utiliser la routine SetupDmaEngineWithBdl .

Avant d’appeler SetupDmaEngineWithBdl pour configurer un moteur DMA, le client doit appeler AllocateCaptureDmaEngine ou AllocateRenderDmaEngine pour allouer le moteur DMA. Le paramètre handle est la valeur obtenue à partir de l’appel précédent à Allocate XxxDmaEngine.

L’appelant est responsable de la programmation du codec pour gérer les transferts de données et reconnaître l’identificateur de flux.

Un pilote audio WDM appelle cette routine au moment de la création du code confidentiel lors de l’exécution de sa méthode NewStream (par exemple, voir IMiniportWavePci ::NewStream).

Après l’appel à SetupDmaEngineWithBdl, le moteur DMA est à l’état Réinitialiser. Pour démarrer le moteur DMA, appelez SetDmaEngineState.

Le paramètre isr spécifie l’ISR que le pilote de bus AUDIO HD doit appeler chaque fois qu’une interruption IOC se produit sur le flux. Ce paramètre est un pointeur de fonction de type HDAUDIO_BDL_ISR, qui est défini comme suit :

typedef void
  (*PHDAUDIO_BDL_ISR)
    (IN VOID *Context, IN ULONG InterruptBitMask);

Le pilote de bus Audio HD appelle l’ISR avec la même valeur de contexte que celle spécifiée par le client dans le paramètre de contexte de l’appel SetupDmaEngineWithBdl précédent. Le paramètre interruptBitMask contient les bits du flux du périphérique de contrôleur audio HD status enregistrer qui indiquent la raison de l’interruption. Le tableau suivant montre la signification des bits individuels dans interruptBitMask.

Nombres de bits	Signification
31:5	Inutilisé.
4	Erreur de descripteur (DESE). Si une erreur se produit lors de l’extraction d’un descripteur de mémoire tampon, le contrôleur Audio HD définit le bit DESE sur 1.
3	Erreur FIFO (FIFOE). Si une erreur FIFO se produit (un dépassement sur un flux de sortie ou une sous-exécution sur un flux d’entrée), le contrôleur Audio HD définit le bit FIFOE sur 1.
2	État de l’interruption d’achèvement de la mémoire tampon (BCIS). Si le bit IOC est défini sur 1 dans l’octet de commande du descripteur de mémoire tampon, le contrôleur Audio HD définit le bit BCIS sur 1 après le traitement du dernier échantillon d’une mémoire tampon.
1:0	Inutilisé.

Le pilote de bus HD Audio définit les bits inutilisés sur zéro. Au lieu de supposer qu’une interruption ioc s’est produite, l’ISR doit toujours case activée le paramètre interruptBitMask pour déterminer si une erreur de flux s’est produite. Pour plus d’informations sur l’interruption status bits indiqués dans le tableau précédent, consultez la description du flux status registres dans la spécification audio haute définition Intel.

La taille FIFO est le nombre maximal d’octets que le moteur DMA peut contenir dans sa mémoire tampon interne à tout moment. Selon l’implémentation matérielle, la taille FIFO d’un moteur DMA peut être statique ou varier dynamiquement en fonction des modifications apportées au format de flux. Pour plus d’informations sur la taille FIFO, consultez la spécification audio haute définition Intel.

L’appelant doit allouer la mémoire tampon et le BDL à partir du pool non paginé.