PALLOCATE_CAPTURE_DMA_ENGINE fonction de rappel (hdaudio.h)

Article
02/07/2025

La routine AllocateCaptureDmaEngine alloue un moteur DMA pour un flux de capture.

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

Syntaxe

PALLOCATE_CAPTURE_DMA_ENGINE PallocateCaptureDmaEngine;

NTSTATUS PallocateCaptureDmaEngine(
  [in]  PVOID _context,
  [in]  UCHAR CodecAddress,
  [in]  PHDAUDIO_STREAM_FORMAT StreamFormat,
  [out] PHANDLE Handle,
  [out] PHDAUDIO_CONVERTER_FORMAT ConverterFormat
)
{...}

Paramètres

[in] _context

Spécifie la valeur de contexte du membre context du HDAUDIO_BUS_INTERFACE, HDAUDIO_BUS_INTERFACE_V2 ou HDAUDIO_BUS_INTERFACE_BDL structure.

[in] CodecAddress

Spécifie une adresse de codec. Ce paramètre identifie les données série dans la ligne SDI sur laquelle le codec fournit les données de capture au contrôleur de bus AUDIO HD. Un contrôleur de bus avec n broches SDI peut prendre en charge jusqu’à n codecs n avec des adresses comprises entre 0 et n-1.

[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.

[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

AllocateCaptureDmaEngine retourne STATUS_SUCCESS si l’appel réussit à réserver un moteur DMA. Sinon, les valeurs de retour possibles incluent les codes d’erreur dans le tableau suivant.

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 capture 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 AllocateCaptureDmaEngine 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 à AllocateCaptureDmaEngine, le format du flux peut être modifié en appelant ChangeBandwidthAllocation.

Via le handle paramètre, 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 d’entrée. 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 à AllocateCaptureDmaEngine, 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 (Windows Driver Model) appelle AllocateCaptureDmaEngine au moment de la création du code pin pendant l’exécution de sa méthode NewStream (par exemple, voir IMiniportWavePci ::NewStream).