PALLOCATE_RENDER_DMA_ENGINE Rückruffunktion (hdaudio.h)
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 |
---|---|
|
Gibt an, dass die DMA-Engine nicht genügend internen FIFO-Speicher zuordnen kann, um das angeforderte Streamformat zu unterstützen. |
|
Gibt an, dass entweder keine DMA-Engine verfügbar ist oder die Anforderung die verfügbaren Bandbreitenressourcen überschreitet. |
|
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.
AllocateRenderDmaEngine
von 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 AllocateRenderDmaEngine
befindet 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).
Anforderungen
Anforderung | Wert |
---|---|
Zielplattform | Desktop |
Kopfzeile | hdaudio.h (hdaudio.h einschließen) |
IRQL | PASSIVE_LEVEL |