PALLOCATE_CAPTURE_DMA_ENGINE Rückruffunktion (hdaudio.h)

Artikel
02/07/2025

Die AllocateCaptureDmaEngine Routine weist ein DMA-Modul für einen Aufnahmedatenstrom zu.

Der Funktionszeigertyp für eine AllocateCaptureDmaEngine Routine wird wie folgt definiert.

Syntax

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
)
{...}

Parameter

[in] _context

Gibt den Kontextwert aus dem Context Member des HDAUDIO_BUS_INTERFACE, HDAUDIO_BUS_INTERFACE_V2 oder HDAUDIO_BUS_INTERFACE_BDL Struktur an.

[in] CodecAddress

Gibt eine Codecadresse an. Dieser Parameter identifiziert die seriellen Daten in einer SDI-Zeile, in der der Codec die Aufnahmedaten an den HD-Audiobuscontroller bereitstellt. Ein Buscontroller mit n SDI-Pins kann bis zu n Codecs mit Adressen zwischen 0 und n-1 unterstützen.

[in] StreamFormat

Gibt das angeforderte Datenstromformat an. Dieser Parameter verweist auf eine vom Aufrufer zugewiesene Struktur des Typs HDAUDIO_STREAM_FORMAT, die ein Datenformat für den Datenstrom angibt.

[out] Handle

Ruft den Handle zum DMA-Modul ab. Dieser Parameter verweist auf eine handle-Variable, in die die Routine ein Handle schreibt, das das DMA-Modul identifiziert.

[out] ConverterFormat

Ruft das Konverterformat ab. Dieser Parameter verweist auf eine vom Aufrufer zugewiesene Struktur des Typs HDAUDIO_CONVERTER_FORMAT, in die die Routine das codierte Format schreibt.

Rückgabewert

AllocateCaptureDmaEngine gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich ein DMA-Modul reserviert. Andernfalls enthalten mögliche Rückgabewerte die Fehlercodes in der folgenden Tabelle.

Rückgabecode	Beschreibung
STATUS_BUFFER_TOO_SMALL	Gibt an, dass das DMA-Modul nicht genügend internen FIFO-Speicher zuordnen kann, um das angeforderte Datenstromformat zu unterstützen.
STATUS_INSUFFICIENT_RESOURCES	Gibt an, dass entweder kein DMA-Modul verfügbar ist oder die Anforderung die verfügbaren Bandbreitenressourcen überschreitet.
STATUS_INVALID_PARAMETER	Gibt an, dass einer der Parameterwerte falsch ist (ungültiger Parameterwert oder ungültiger Zeiger).

Bemerkungen

Diese Routine weist ein DMA-Aufnahmemodul zu und gibt das Datenformat für den Datenstrom an. Bei erfolgreicher Ausführung gibt die Routine einen Handle aus, den der Aufrufer anschließend verwendet, um das DMA-Modul zu identifizieren.

Die AllocateCaptureDmaEngine Routine reserviert Hardwareressourcen (das DMA-Modul), konfiguriert jedoch nicht die DMA-Hardware. Nach dem Aufrufen dieser Routine zum Reservieren eines DMA-Moduls muss ein Funktionstreiber dem DMA-Modul einen DMA-Puffer zuweisen und das Modul so konfigurieren, dass er den Puffer verwendet:

Wenn Sie die HDAUDIO_BUS_INTERFACE Version der HD Audio DDI verwenden, ruft der Funktionstreiber die AllocateDmaBuffer-Routine auf, damit der HD-Audiobustreiber einen Datenpuffer für DMA-Übertragungen zuweist und das DMA-Modul für die Verwendung des Puffers einrichten kann.
Wenn Sie die HDAUDIO_BUS_INTERFACE_BDL Version der DDI verwenden, ruft der Funktionstreiber AllocateContiguousDmaBuffer auf, um den DMA-Puffer zuzuweisen, und ruft die SetupDmaEngineWithBdl Routine auf, um das DMA-Modul für die Verwendung des Puffers einzurichten.

Der parameter streamFormat gibt das Datenformat für den Aufnahmedatenstrom an. Nach dem Aufruf von AllocateCaptureDmaEnginekann das Format des Datenstroms durch Aufrufen ChangeBandwidthAllocationgeändert werden.

Über den handle Parameter, die Routine gibt einen Handle aus, den der Aufrufer verwendet, um das zugeordnete DMA-Modul in nachfolgenden Aufrufen an AllocateDmaBuffer, ChangeBandwidthAllocation, FreeDmaBuffer, SetupDmaEngineWithBdlund SetDmaEngineState. Der Funktionstreiber gibt den Handle frei, indem FreeDmaEngineaufgerufen wird.

Über den converterFormat Parameter gibt die Routine einen Datenstromdeskriptorwert aus, den der Aufrufer zum Programmieren der Eingabekonverter verwenden kann. Die Routine codiert die Informationen aus dem streamFormat Parameter in eine 16-Bit-Ganzzahl. Weitere Informationen finden Sie unter HDAUDIO_CONVERTER_FORMAT.

Unmittelbar nach einem erfolgreichen Aufruf von AllocateCaptureDmaEnginebefindet sich das DMA-Modul im Zustand "Datenstrom zurücksetzen". Bevor Sie SetDmaEngineState- aufrufen, um das DMA-Modul in den ausgeführten, angehaltenen oder angehaltenen Zustand zu ändern, muss der Client zunächst einen DMA-Puffer für das Modul zuweisen.

Ein Windows Driver Model (WDM)-Audiotreiber ruft während der Ausführung der NewStream--Methode AllocateCaptureDmaEngine zur Pinerstellungszeit auf (siehe z. B. IMiniportWavePci::NewStream).