PALLOCATE_RENDER_DMA_ENGINE fonction de rappel (hdaudio.h)

Article
08/07/2023

La AllocateRenderDmaEngine routine alloue un moteur DMA pour un flux de rendu.

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

Syntaxe

PALLOCATE_RENDER_DMA_ENGINE PallocateRenderDmaEngine;

NTSTATUS PallocateRenderDmaEngine(
  [in]  PVOID _context,
  [in]  PHDAUDIO_STREAM_FORMAT StreamFormat,
  [in]  BOOLEAN Stripe,
  [out] PHANDLE Handle,
  [out] PHDAUDIO_CONVERTER_FORMAT ConverterFormat
)
{...}

Paramètres

[in] _context

Spécifie la valeur de contexte des membres de contexte des structures HDAUDIO_BUS_INTERFACE,HDAUDIO_BUS_INTERFACE_V2 ou HDAUDIO_BUS_INTERFACE_BDL.

[in] StreamFormat

Spécifie le format de flux demandé. Ce paramètre pointe vers une structure allouée par l’appelant de type HDAUDIO_STREAM_FORMAT qui spécifie un format de données pour le flux.

[in] Stripe

Spécifie s’il faut activer l’entrelacement. Si la valeur est TRUE, la routine active l’entrelacement dans les transferts DMA. Si la valeur est FALSE, l’entrelacement est désactivé.

[out] Handle

Récupère le handle dans le moteur DMA. Ce paramètre pointe vers une variable HANDLE allouée à l’appelant dans laquelle la routine écrit un handle qui identifie le moteur DMA.

[out] ConverterFormat

Récupère le format du convertisseur. Ce paramètre pointe vers une structure allouée par l’appelant de type HDAUDIO_CONVERTER_FORMAT dans laquelle la routine écrit le format codé.

Valeur retournée

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

Code de retour	Description
STATUS_BUFFER_TOO_SMALL	Indique que le moteur DMA ne peut pas allouer suffisamment de stockage FIFO interne pour prendre en charge le format de flux demandé.
STATUS_INSUFFICIENT_RESOURCES	Indique qu’aucun moteur DMA n’est disponible ou que la requête dépasse les ressources de bande passante disponibles.
STATUS_INVALID_PARAMETER	Indique que l’une des valeurs de paramètre est incorrecte (valeur de paramètre non valide ou pointeur incorrect).

Remarques

Cette routine alloue un moteur DMA de rendu et spécifie le format de données pour le flux. En cas de réussite, la routine génère un handle que l’appelant utilise par la suite pour identifier le moteur DMA.

La AllocateRenderDmaEngine routine réserve les ressources matérielles (le moteur DMA), mais ne configure pas le matériel DMA. Après avoir appelé cette routine pour réserver un moteur DMA, un pilote de fonction doit affecter une mémoire tampon DMA au moteur DMA et configurer le moteur pour utiliser la mémoire tampon :

Si vous utilisez la version HDAUDIO_BUS_INTERFACE de hd Audio DDI, le pilote de fonction appelle la routine AllocateDmaBuffer pour que le pilote de bus Audio HD alloue une mémoire tampon de données pour les transferts DMA et configure le moteur DMA pour utiliser la mémoire tampon.
Si vous utilisez la version HDAUDIO_BUS_INTERFACE_BDL de la DDI, le pilote de fonction appelle AllocateContiguousDmaBuffer pour allouer la mémoire tampon DMA et appelle la routine SetupDmaEngineWithBdl pour configurer le moteur DMA afin d’utiliser la mémoire tampon.

Le paramètre streamFormat spécifie le format de données du flux de capture. Après l’appel à AllocateRenderDmaEngine, le format du flux peut être modifié en appelant ChangeBandwidthAllocation.

Le paramètre stripe spécifie si le moteur DMA doit utiliser l’entrelacement pour accélérer les transferts de données. Pour plus d’informations, consultez Striping.

Grâce au paramètre handle, la routine génère un handle que l’appelant utilise pour identifier le moteur DMA alloué dans les appels suivants à AllocateDmaBuffer, ChangeBandwidthAllocation, FreeDmaBuffer, SetupDmaEngineWithBdl et SetDmaEngineState. Le pilote de fonction libère le handle en appelant FreeDmaEngine.

Par le biais du paramètre converterFormat , la routine génère une valeur de descripteur de flux que l’appelant peut utiliser pour programmer les convertisseurs de sortie. La routine encode les informations du paramètre streamFormat dans un entier 16 bits. Pour plus d’informations, consultez HDAUDIO_CONVERTER_FORMAT.

Immédiatement après un appel réussi à AllocateRenderDmaEngine, le moteur DMA est dans l’état de réinitialisation du flux. Avant d’appeler SetDmaEngineState pour remplacer le moteur DMA par l’état en cours d’exécution, en pause ou arrêté, le client doit d’abord allouer une mémoire tampon DMA pour le moteur.

Un pilote audio WDM appelle AllocateRenderDmaEngine au moment de la création d’un code confidentiel pendant l’exécution de sa méthode NewStream (par exemple, consultez IMiniportWavePci ::NewStream).