PALLOCATE_CAPTURE_DMA_ENGINE Rückruffunktion (hdaudio.h)

Artikel
02/29/2024

Die AllocateCaptureDmaEngine Routine weist eine DMA-Engine für einen Erfassungsdatenstrom zu.

Der Funktionszeigertyp für eine AllocateCaptureDmaEngine Routine ist 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 Kontextelement der 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 der Zeile (SDI), auf der der Codec die Aufnahmedaten an den HD-Audiobuscontroller bereitstellt. Ein Buscontroller mit n SDI-Pins kann bis zu n Codecs mit Adressen von 0 bis n-1 unterstützen.

[in] StreamFormat

Gibt das angeforderte Streamformat an. Dieser Parameter verweist auf eine vom Aufrufer zugeordnete Struktur vom Typ HDAUDIO_STREAM_FORMAT , die ein Datenformat für den Stream angibt.

[out] Handle

Ruft das Handle an die DMA-Engine ab. Dieser Parameter verweist auf eine vom Aufrufer zugewiesene HANDLE-Variable, in die die Routine ein Handle schreibt, das die DMA-Engine identifiziert.

[out] ConverterFormat

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

Rückgabewert

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

Rückgabecode	Beschreibung
STATUS_BUFFER_TOO_SMALL	Gibt an, dass die DMA-Engine nicht genügend internen FIFO-Speicher zuordnen kann, um das angeforderte Streamformat zu unterstützen.
STATUS_INSUFFICIENT_RESOURCES	Gibt an, dass entweder keine DMA-Engine 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).

Hinweise

Diese Routine ordnet eine DMA-Engine für die Erfassung zu und gibt das Datenformat für den Stream an. Bei erfolgreicher Ausführung gibt die Routine ein Handle aus, das der Aufrufer anschließend verwendet, um die DMA-Engine zu identifizieren.

Die AllocateCaptureDmaEngine Routine reserviert Hardwareressourcen (DMA-Engine), konfiguriert aber nicht die DMA-Hardware. Nach dem Aufrufen dieser Routine zum Reservieren einer DMA-Engine muss ein Funktionstreiber der DMA-Engine einen DMA-Puffer zuweisen und die Engine für die Verwendung des Puffers konfigurieren:

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

Der streamFormat-Parameter gibt das Datenformat für den Erfassungsdatenstrom an. Nach dem Aufruf AllocateCaptureDmaEnginevon kann das Format des Streams geändert werden, indem ChangeBandwidthAllocation aufgerufen wird.

Über den handle-Parameter gibt die Routine ein Handle aus, das der Aufrufer verwendet, um die zugeordnete DMA-Engine in nachfolgenden Aufrufen von AllocateDmaBuffer, ChangeBandwidthAllocation, FreeDmaBuffer, SetupDmaEngineWithBdl und SetDmaEngineState zu identifizieren. Der Funktionstreiber gibt das Handle durch Aufrufen von FreeDmaEngine frei.

Über den parameter converterFormat gibt die Routine einen Streamdeskriptorwert 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 die DMA-Engine im Status "Stream zurücksetzen". Bevor SetDmaEngineState aufgerufen wird, um die DMA-Engine in den Zustand "Running", "Paused" oder "Stopped" zu ändern, muss der Client zunächst einen DMA-Puffer für die Engine zuweisen.

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