PSETUP_DMA_ENGINE_WITH_BDL fonction de rappel (hdaudio.h)

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,
        ULONG BufferLength,
  [in]  ULONG Lvi,
  [in]  PHDAUDIO_BDL_ISR Isr,
        PVOID Context,
  [out] PUCHAR StreamId,
  [out] PULONG FifoSize
)
{...}

Paramètres

[in] _context

Spécifie la valeur de contexte du membre de contexte 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.

BufferLength

[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 continue de traiter. Si bdL contient n descripteurs, ils sont numérotés de 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 (IOC) dans un ou plusieurs de ces descripteurs de mémoire tampon dans 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.

Context

[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’il 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 à 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.

Code de retour Description
STATUS_UNSUCCESSFUL
Indique que l’appelant s’exécute à 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, 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 AllContiguousDmaBuffer pour allouer le stockage dans la mémoire système à la fois pour la mémoire tampon DMA et le 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 respecter les exigences d’alignement décrites dans la spécification audio Intel High Definition (voir 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 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’il n’est plus nécessaire.

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 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 handle est la valeur obtenue à partir de l’appel précédent pour Allouer 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 pin lors de l’exécution de sa méthode NewStream (par exemple, voir IMiniportWavePci::NewStream).

Après l’appel à SetupDmaEngineWithBdl, le moteur DMA est dans 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 de l’appel SetupDmaEngineWithBdl précédent. Le paramètre interruptBitMask contient les bits du registre d’état du flux du contrôleur HD audio 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 un 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 exemple 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 affichés dans le tableau précédent, consultez la description des registres d’état de flux dans la spécification audio Intel High Definition.

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 audio Intel High Definition.

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

Configuration requise

   
Plateforme cible Desktop (Expérience utilisateur)
En-tête hdaudio.h (include Hdaudio.h)
IRQL PASSIVE_LEVEL

Voir aussi

AllocationCaptureDmaEngine

AllocationDmaBuffer

AllocationRenderDmaEngine

FreeDmaBuffer

HDAUDIO_BUFFER_DESCRIPTOR

HDAUDIO_BUS_INTERFACE_BDL

SetDmaEngineState