PALLOCATE_CONTIGUOUS_DMA_BUFFER fonction de rappel (hdaudio.h)

Article
02/26/2024

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

Le type de pointeur de fonction pour une AllocateContiguousDmaBuffer routine 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 le BDL commence sur une limite de page.

Valeur retournée

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

Code de retour	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 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 à l’état de réinitialisation ou qu’une mémoire tampon est déjà allouée pour le moteur DMA.

Remarques

La AllocateContiguousDmaBuffer routine est utilisée conjointement avec les routines SetupDmaEngineWithBdl et FreeContiguousDmaBuffer . Ces trois routines sont disponibles uniquement dans la version HDAUDIO_BUS_INTERFACE_BDL du DDI Audio HD. 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 tous deux allouent une mémoire tampon DMA et configurent le moteur DMA pour utiliser la mémoire tampon. Pour plus d’informations, consultez Différences entre les deux versions de 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 le BDL. Selon l’architecture du processeur hôte, une taille de page standard peut être de 4 096 ou 8 192 octets. La mémoire tampon de données se compose d’un seul bloc contigu de mémoire physique.

Le paramètre 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 BDL avant de l’envoyer à 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 IOC à intervalles précis, le pilote de fonction peut être amené à 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 Audio haute définition Intel (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 du suivant. Lors de l’appel de 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 sera inférieure ou égale au nombre d’octets spécifié dans le paramètre requestedBufferSize de la AllocateContiguousDmaBuffer routine.

Pendant la durée de vie d’un handle de moteur DMA, AllocateContiguousDmaBuffer peut être appelé 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.

Lors des appels à AllocateContiguousDmaBuffer, SetupDmaEngineWithBdl et FreeContiguousDmaBuffer, le moteur DMA doit être à l’état de réinitialisation du flux. Le moteur DMA est à l’état de réinitialisation immédiatement après l’appel à AllouerXxxDmaEngine. Pour modifier l’état d’exécution du moteur DMA, appelez SetDmaEngineState.

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

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