PALLOCATE_CONTIGUOUS_DMA_BUFFER fonction de rappel (hdaudio.h)

Article
02/07/2025

La routine AllocateContiguousDmaBuffer alloue une mémoire tampon DMA qui se compose d’un bloc de mémoire physique unique et contigu.

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

Syntaxe

PALLOCATE_CONTIGUOUS_DMA_BUFFER PallocateContiguousDmaBuffer;

NTSTATUS PallocateContiguousDmaBuffer(
  [in]  PVOID _context,
  [in]  HANDLE Handle,
        ULONG RequestedBufferSize,
  [out] PVOID *DataBuffer,
  [out] PHDAUDIO_BUFFER_DESCRIPTOR *BdlBuffer
)
{...}

Paramètres

[in] _context

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

[in] Handle

Gérer l’identification du moteur DMA. Cette valeur de handle a été obtenue à partir d’un appel précédent à AllocateCaptureDmaEngine ou AllocateRenderDmaEngine.

RequestedBufferSize

Spécifie la taille de mémoire tampon demandée en octets.

[out] DataBuffer

Récupère la mémoire tampon de données. Ce paramètre pointe vers une variable PVOID allouée par l’appelant dans laquelle la routine écrit l’adresse virtuelle système de la mémoire tampon de données.

[out] BdlBuffer

Récupère la liste de descripteurs de mémoire tampon (BDL). Ce paramètre pointe vers une variable PVOID allouée par l’appelant dans laquelle la routine écrit l’adresse virtuelle système du BDL. La taille d’allocation BDL est exactement une page de mémoire et la bibliothèque BDL commence sur une limite de page.

Valeur de retour

AllocateContiguousDmaBuffer 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 s’exécute à un niveau de demande d’interruption (IRQL) trop élevé.
STATUS_INSUFFICIENT_RESOURCES	Indique que l’allocation de mémoire tampon a échoué.
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).
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 le flux n’est pas dans l’état de réinitialisation ou qu’une mémoire tampon est déjà allouée pour le moteur DMA.

Remarques

La routine AllocateContiguousDmaBuffer est utilisée conjointement avec les routines SetupDmaEngineWithBdl 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 qu’il utilise 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. Pour plus d’informations, consultez différences entre les deux versions DDI.

AllocateContiguousDmaBuffer alloue une mémoire tampon de données pour le moteur DMA spécifié. Il alloue également une page de mémoire pour la bibliothèque BDL. Selon l’architecture du processeur hôte, une taille de page classique peut être de 4 096 ou 8 192 octets. La mémoire tampon de données se compose d’un bloc de mémoire physique unique et contigu.

Le paramètre de handle spécifie le moteur DMA qui doit utiliser la mémoire tampon de données et BDL. La routine alloue le stockage qui répond aux exigences de taille, d’alignement et de position du moteur DMA.

Le stockage que la routine alloue pour la mémoire tampon de données et BDL n’est pas initialisé. Le pilote de fonction est chargé de remplir le fichier BDL avant de le soumettre à la routine SetupDmaEngineWithBdl. Le pilote de fonction est également responsable de la programmation du codec pour gérer les transferts de données et reconnaître l’identificateur de flux.

Pour générer des interruptions CIO à intervalles précis, le pilote de fonction peut être nécessaire pour diviser l’allocation de mémoire tampon de données en plusieurs fragments d’une taille particulière. Chaque fragment est décrit par une entrée BDL. La taille du fragment peut être ajustée pour régler le taux d’interruption. Selon la spécification Intel High Definition Audio (voir le site web Intel HD Audio), chaque fragment doit commencer sur une limite de 128 octets, bien qu’aucune exigence d’alignement ne s’applique à la longueur du fragment. Ainsi, un écart peut exister entre la fin d’un fragment et le début de la suivante. Lorsque vous appelez SetupDmaEngineWithBdl, le pilote de fonction doit spécifier une valeur pour le paramètre bufferSize qui représente la somme des tailles des fragments individuels décrits par les entrées BDL. Cette taille est inférieure ou égale au nombre d’octets spécifié dans le paramètre de la routine AllocateContiguousDmaBuffer demandéBufferSize.

Pendant la durée de vie d’un handle de moteur DMA, AllocateContiguousDmaBuffer peut être appelée successivement pour allouer de nouvelles mémoires tampons DMA. Toutefois, avant d’appeler AllocateContiguousDmaBuffer, toute mémoire tampon DMA précédemment allouée doit d’abord être libérée en appelant FreeContiguousDmaBuffer.

Pendant les appels à AllocateContiguousDmaBuffer, SetupDmaEngineWithBdlet FreeContiguousDmaBuffer, le moteur DMA doit être dans l’état du flux de réinitialisation. Le moteur DMA est à l’état de réinitialisation immédiatement après l’appel d’AllocationXxxDmaEngine. Pour remplacer le moteur DMA par l’état d’exécution, appelez SetDmaEngineState.

Cette routine échoue et retourne le code d’erreur STATUS_INVALID_DEVICE_REQUEST dans l’une des circonstances suivantes :

Toute mémoire tampon DMA précédemment allouée n’a pas été libérée (en appelant FreeContiguousDmaBuffer).
Le flux est dans un état autre que la réinitialisation.