PALLOCATE_RENDER_DMA_ENGINE Rückruffunktion (hdaudio.h)

Artikel
02/29/2024

Die AllocateRenderDmaEngine Routine ordnet eine DMA-Engine für einen Renderdatenstrom zu.

Der Funktionszeigertyp für eine AllocateRenderDmaEngine Routine ist wie folgt definiert.

Syntax

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

Parameter

[in] _context

Gibt den Kontextwert aus den Kontextmembern der HDAUDIO_BUS_INTERFACE-,HDAUDIO_BUS_INTERFACE_V2- oder HDAUDIO_BUS_INTERFACE_BDL-Strukturen an.

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

[in] Stripe

Gibt an, ob das Striping aktiviert werden soll. Wenn TRUE, aktiviert die Routine das Striping in den DMA-Übertragungen. Bei FALSE ist das Striping deaktiviert.

[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

AllocateRenderDmaEngine gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich eine DMA-Engine reserviert. Andernfalls gibt die Routine einen geeigneten Fehlercode zurück. In der folgenden Tabelle sind einige der möglichen Rückgabefehlercodes aufgeführt.

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 Render-DMA-Engine 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 AllocateRenderDmaEngine 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 AllocateRenderDmaEnginevon kann das Format des Streams geändert werden, indem ChangeBandwidthAllocation aufgerufen wird.

Der Stripe-Parameter gibt an, ob die DMA-Engine Striping verwenden soll, um Datenübertragungen zu beschleunigen. Weitere Informationen finden Sie unter Striping.

Ü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 Ausgabekonverter 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 AllocateRenderDmaEnginebefindet 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 ruft AllocateRenderDmaEngine während der Ausführung seiner NewStream-Methode zum Zeitpunkt der Pinerstellung auf (siehe z. B . IMiniportWavePci::NewStream).