PALLOCATE_CAPTURE_DMA_ENGINE fonction de rappel (hdaudio.h)

Article
08/07/2023

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

Le type de pointeur de fonction pour une AllocateCaptureDmaEngine routine 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 de la structure HDAUDIO_BUS_INTERFACE, HDAUDIO_BUS_INTERFACE_V2 ou HDAUDIO_BUS_INTERFACE_BDL .

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

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

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

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.

Via le 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 dans un 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 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 (Windows Driver Model) appelle AllocateCaptureDmaEngine au moment de la création d’une broche lors de l’exécution de sa méthode NewStream (par exemple, voir IMiniportWavePci ::NewStream).