PALLOCATE_RENDER_DMA_ENGINE fonction de rappel (hdaudio.h)

Article
02/07/2025

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

Le type de pointeur de fonction pour une routine AllocateRenderDmaEngine 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 Context des structures HDAUDIO_BUS_INTERFACE,HDAUDIO_BUS_INTERFACE_V2ou 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 le striping. Si TRUE, la routine active le striping dans les transferts DMA. Si faux, le striping est désactivé.

[out] Handle

Récupère le handle sur le moteur DMA. Ce paramètre pointe vers une variable HANDLE allouée par 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 encodé.

Valeur de retour

AllocateRenderDmaEngine retourne STATUS_SUCCESS si l’appel réussit à réserver 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.

Retourner le code	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 qu’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 du flux. Si elle réussit, la routine génère un handle que l’appelant utilise par la suite pour identifier le moteur DMA.

La routine AllocateRenderDmaEngine réserve des 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 le AllocateDmaBuffer routine 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 pour 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 bande spécifie si le moteur DMA doit utiliser le striping pour accélérer les transferts de données. Pour plus d’informations, consultez striping .

Par le biais du paramètre de 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, SetupDmaEngineWithBdlet SetDmaEngineState. Le pilote de fonction libère le handle en appelant FreeDmaEngine.

Grâce au 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 en 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 du flux de réinitialisation. Avant d’appeler SetDmaEngineState pour remplacer le moteur DMA par l’état en cours d’exécution, suspendu 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 du code pin pendant l’exécution de sa méthode NewStream (par exemple, voir IMiniportWavePci ::NewStream).