PSETUP_DMA_ENGINE_WITH_BDL fonction de rappel (hdaudio.h)

Article
02/07/2025

La routine SetupDmaEngineWithBdl configure un moteur DMA pour utiliser une mémoire tampon DMA allouée par 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 bdL. Une fois que le moteur DMA traite ce descripteur, il revient au premier descripteur de la liste et poursuit le traitement. Si bdL contient n descripteurs, ils sont numérotés 0 à n-1. La valeur lvi doit être au moins 1 ; en d’autres termes, le BDL doit contenir au moins deux entrées valides avant que le moteur DMA puisse commencer l’opération.

[in] Isr

Pointeur de fonction vers l’ISR de l’appelant. Si l’appelant définit le bit d’interruption sur la saisie semi-automatique (CIO) dans un ou plusieurs de ses descripteurs de mémoire tampon dans le BDL, le pilote de bus AUDIO HD appelle l’ISR chaque fois qu’une interruption DU CIO 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 Remarques suivante.

[in] Context

Contexte.

[out] StreamId

Récupère l’identificateur de flux. Ce paramètre pointe vers une variable UCHAR allouée par 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 de retour

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 d’état de retour possibles.

Retourner le code	Description
STATUS_UNSUCCESSFUL	Indique que l’appelant est en cours d’exécution à un irQL trop élevé.
STATUS_INVALID_HANDLE	Indique que la valeur du paramètre de handle n’est pas valide.
STATUS_INVALID_PARAMETER	Indique qu’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 de réinitialisation.

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, SetupDmaEngineWithBdlet FreeContiguousDmaBuffer. Contrairement à SetupDmaEngineWithBdl, qui configure le moteur DMA pour utiliser une mémoire tampon DMA précédemment allouée, AllocateDmaBuffer alloue une mémoire tampon DMA et configure le moteur DMA pour utiliser la mémoire tampon.

L’appelant doit appeler AllocateContiguousDmaBuffer pour allouer le 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 intel high definition audio (consultez le site web Intel HD Audio).

La mémoire BDL et la mémoire tampon qu’elle décrit doivent rester valides pendant les opérations DMA. Après l’appel à SetupDmaEngineWithBdl, la mémoire BDL et la mémoire tampon doivent rester valides tant que le moteur DMA continue d’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 SetupDmaEngineWithBdl ou libère à nouveau 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. Ainsi, 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 de handle est la valeur obtenue à partir de l’appel précédent pour Allouer XxxDmaEngine.

L’appelant est chargé de programmer le 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 pin pendant l’exécution de sa méthode NewStream (par exemple, voir IMiniportWavePci ::NewStream).

Après l’appel à SetupDmaEngineWithBdl, le moteur DMA est à l’état de réinitialisation. 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 DU CIO 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 le client spécifié dans le paramètre de contexte du SetupDmaEngineWithBdl précédent appel. Le paramètre interruptBitMask contient les bits du registre d’état du flux du contrôleur audio HD 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 (dépassement d’un flux de sortie ou d’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 CIO 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 dernier échantillon d’une mémoire tampon traité.
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 DU CIO s’est produite, l’ISR doit toujours vérifier le paramètre interruptBitMask pour déterminer si une erreur de flux s’est produite. Pour plus d’informations sur les bits d’état d’interruption indiqués dans le tableau précédent, consultez la description des registres d’état de flux dans la spécification Intel High Definition Audio.

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 avec les modifications apportées au format de flux. Pour plus d’informations sur la taille FIFO, consultez la Spécification d’Intel High Definition Audio.

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