PALLOCATE_DMA_BUFFER Rückruffunktion (hdaudio.h)

Artikel
02/07/2025

Die AllocateDmaBuffer Routine weist einen Datenpuffer im Systemspeicher für ein DMA-Modul zu.

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

Syntax

PALLOCATE_DMA_BUFFER PallocateDmaBuffer;

NTSTATUS PallocateDmaBuffer(
  [in]  PVOID _context,
  [in]  HANDLE Handle,
  [in]  SIZE_T RequestedBufferSize,
  [out] PMDL *BufferMdl,
  [out] PSIZE_T AllocatedBufferSize,
  [out] PUCHAR StreamId,
  [out] PULONG FifoSize
)
{...}

Parameter

[in] _context

Gibt den Kontextwert aus den Context- Membern der HDAUDIO_BUS_INTERFACE- und HDAUDIO_BUS_INTERFACE_V2-Strukturen an.

[in] Handle

Behandeln Sie die Identifizierung des DMA-Moduls. Dieser Handlewert wurde aus einem vorherigen Aufruf von AllocateCaptureDmaEngine oder AllocateRenderDmaEngineabgerufen.

[in] RequestedBufferSize

Gibt die angeforderte Puffergröße in Byte an.

[out] BufferMdl

Ruft die physischen Speicherseiten ab, die den zugeordneten Puffer enthalten. Dieser Parameter verweist auf eine vom Aufrufer zugewiesene PMDL-Variable, in die die Routine einen Zeiger auf eine Speicherdeskriptorliste (MDL) schreibt, die den Puffer beschreibt.

[out] AllocatedBufferSize

Ruft die zugeordnete Puffergröße in Bytes ab. Dieser Parameter verweist auf eine vom Aufrufer zugewiesene SIZE_T Variable, in die die Routine die Größe des zugeordneten Puffers schreibt.

[out] StreamId

Ruft den Datenstrombezeichner ab. Dieser Parameter verweist auf eine vom Aufrufer zugewiesene UCHAR-Variable, in die die Routine den Datenstrombezeichner schreibt, den er dem Datenstrom zuweist.

[out] FifoSize

Ruft die FIFO-Größe des DMA-Moduls in Byte ab. Dieser Parameter verweist auf eine vom Aufrufer zugewiesene ULONG-Variable, in die die FIFO-Größe von der Routine geschrieben wird.

Rückgabewert

AllocateDmaBuffer gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich ist. Andernfalls gibt die Routine einen geeigneten Fehlercode zurück. In der folgenden Tabelle sind einige der möglichen Rückgabestatuscodes aufgeführt.

Rückgabecode	Beschreibung
STATUS_UNSUCCESSFUL	Gibt an, dass der Aufrufer bei einer IRQL ausgeführt wird, die zu hoch ist.
STATUS_INSUFFICIENT_RESOURCES	Gibt an, dass die Pufferzuweisung fehlgeschlagen ist.
STATUS_INVALID_HANDLE	Gibt an, dass der Handle-Parameterwert ungültig ist.
STATUS_INVALID_PARAMETER	Gibt an, dass einer der Parameterwerte falsch ist (ungültiger Zeiger).
STATUS_DEVICE_NOT_READY	Gibt an, dass das Zeitlimit für die Hardwareprogrammierung eingestellt ist. Wenn dies geschieht, befindet sich die Hardware möglicherweise in einem kompromittierten Zustand.
STATUS_INVALID_DEVICE_REQUEST	Gibt an, dass sich der Datenstrom nicht im Zurücksetzungszustand befindet oder dass bereits ein Puffer für das DMA-Modul zugeordnet ist.

Bemerkungen

Die AllocateDmaBuffer Routine wird in Verbindung mit der FreeDmaBuffer Routine verwendet. Diese beiden Routinen sind nur in den HDAUDIO_BUS_INTERFACE und den HDAUDIO_BUS_INTERFACE_V2 Versionen des HD Audio DDI verfügbar. Dieser DDI enthält nicht die AllocateContiguousDmaBuffer, SetupDmaEngineWithBdlund FreeContiguousDmaBuffer Routinen, die nie in Verbindung mit AllocateDmaBuffer und FreeDmaBufferverwendet werden. Im Gegensatz zu SetupDmaEngineWithBdl, das das DMA-Modul so konfiguriert, dass ein zuvor zugewiesener DMA-Puffer verwendet wird, AllocateDmaBuffer beide einen DMA-Puffer zuweisen und das DMA-Modul so konfiguriert, dass der Puffer verwendet wird.

Wenn das DMA-Modul keinen Puffer der im Parameter angeforderten Größe requestedBufferSizeverwenden kann, weist die Routine einen Puffer zu, der der angeforderten Größe so nah wie möglich ist.

Der Funktionstreiber für einen Audio- oder Modemcodec ist für die Programmierung des Codecs für die Verwaltung der Datenübertragungen und für die Erkennung des Datenstrombezeichners verantwortlich.

Die Routine gibt eine MDL aus, die die physischen Speicherseiten auflistet, die den Puffer enthalten. Die Pufferbasisadresse stimmt mit dem Anfang der ersten physischen Seite in der Liste überein.

Während der Lebensdauer eines DMA-Modulhandles können AllocateDmaBuffer nacheinander aufgerufen werden, um neue DMA-Puffer zuzuweisen. Bevor Sie jedoch AllocateDmaBufferaufrufen, müssen alle zuvor zugewiesenen DMA-Puffer zuerst durch Aufrufen FreeDmaBuffer-freigegeben werden.

Bei Aufrufen von AllocateDmaBuffer und FreeDmaBuffer-muss sich das DMA-Modul im Zustand "Stream zurücksetzen" befinden. Das DMA-Modul befindet sich unmittelbar nach dem Aufruf zum ZuweisenXxxDmaEngine im Zustand "Zurücksetzen". Um das DMA-Modul in den Ausführungszustand zu ändern, rufen Sie SetDmaEngineStateauf.

Die FIFO-Größe ist die maximale Anzahl von Bytes, die das DMA-Modul im internen Puffer enthalten kann. Je nach Hardwareimplementierung kann die FIFO-Größe eines DMA-Moduls statisch sein oder dynamisch mit Änderungen im Datenstromformat variieren. Weitere Informationen zur FIFO-Größe finden Sie in der Intel High Definition Audio Specification auf der Website Intel HD Audio.

Diese Routine schlägt fehl und gibt fehlercode STATUS_INVALID_DEVICE_REQUEST in einem der folgenden Situationen zurück:

Alle zuvor zugewiesenen DMA-Puffer wurden nicht freigegeben (durch Aufrufen von FreeDmaBuffer).
Der Datenstrom befindet sich in einem anderen Zustand als "Zurücksetzen".

In Windows Server 2003, Windows XP, Windows 2000 und Windows Me/98 ruft ein WDM-Audiotreiber diese Routine während der Ausführung seiner NewStream-Methode (zur Pinerstellungszeit) oder SetFormat--Methode (nach dem Aufrufen einer derXxxDmaEngine-Routinen in hd Audio DDI) auf. Weitere Informationen finden Sie unter IMiniportWavePci::NewStream und IMiniportWavePciStream::SetFormat.