PALLOCATE_DMA_BUFFER Rückruffunktion (hdaudio.h)

Artikel
02/26/2024

Die AllocateDmaBuffer Routine weist einem DMA-Modul einen Datenpuffer im Systemspeicher zu.

Der Funktionszeigertyp für eine AllocateDmaBuffer Routine ist 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 Kontextmembern der HDAUDIO_BUS_INTERFACE- und HDAUDIO_BUS_INTERFACE_V2-Strukturen an.

[in] Handle

Behandeln Sie die Identifizierung der DMA-Engine. Dieser Handlewert wurde aus einem vorherigen Aufruf von AllocateCaptureDmaEngine oder AllocateRenderDmaEngine abgerufen.

[in] RequestedBufferSize

Gibt die angeforderte Puffergröße in Bytes an.

[out] BufferMdl

Ruft die Seiten des physischen Speichers 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 (Memory Descriptor List, 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 Streambezeichner ab. Dieser Parameter verweist auf eine vom Aufrufer zugewiesene UCHAR-Variable, in die die Routine den Streambezeichner schreibt, den sie dem Stream zuweist.

[out] FifoSize

Ruft die FIFO-Größe der DMA-Engine in Bytes ab. Dieser Parameter verweist auf eine vom Aufrufer zugewiesene ULONG-Variable, in die die Routine die FIFO-Größe schreibt.

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ückgabecodes status aufgeführt.

Rückgabecode	Beschreibung
STATUS_UNSUCCESSFUL	Gibt an, dass der Aufrufer in einem zu hohen IRQL-Wert ausgeführt wird.
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 bei der Hardwareprogrammierung ein Timeout aufgetreten ist. In diesem Fall befindet sich die Hardware möglicherweise in einem kompromittierten Zustand.
STATUS_INVALID_DEVICE_REQUEST	Gibt an, dass sich der Stream nicht im Zurücksetzungszustand befindet oder dass der DMA-Engine bereits ein Puffer zugeordnet ist.

Hinweise

Die AllocateDmaBuffer Routine wird in Verbindung mit der FreeDmaBuffer-Routine verwendet. Diese beiden Routinen sind nur in den HDAUDIO_BUS_INTERFACE- und HDAUDIO_BUS_INTERFACE_V2 Versionen von HD Audio DDI verfügbar. Dieser DDI enthält nicht die Routinen AllocateContiguousDmaBuffer, SetupDmaEngineWithBdl und FreeContiguousDmaBuffer , die nie in Verbindung mit AllocateDmaBuffer und FreeDmaBuffer verwendet werden. Im Gegensatz zu SetupDmaEngineWithBdl, das die DMA-Engine für die Verwendung eines zuvor zugeordneten DMA-Puffers konfiguriert, AllocateDmaBuffer ordnet beide einen DMA-Puffer zu und konfiguriert die DMA-Engine für die Verwendung des Puffers.

Wenn die DMA-Engine keinen Puffer der im Parameter requestedBufferSize angeforderten Größe verwenden kann, weist die Routine einen Puffer zu, der der angeforderten Größe so nahe wie möglich ist.

Der Funktionstreiber für einen Audio- oder Modemcodec ist für die Programmierung des Codecs verantwortlich, um die Datenübertragungen zu verwalten und den Streambezeichner zu erkennen.

Die Routine gibt eine MDL aus, die die physischen Speicherseiten auflistet, die den Puffer enthalten. Die Pufferbasisadresse fällt mit dem Anfang der ersten physischen Seite in der Liste zusammen.

Während der Lebensdauer eines DMA-Engine-Handles kann nacheinander aufgerufen werden, AllocateDmaBuffer um neue DMA-Puffer zuzuweisen. Vor dem Aufrufen AllocateDmaBuffervon muss jedoch jeder zuvor zugeordnete DMA-Puffer durch Aufrufen von FreeDmaBuffer freigegeben werden.

Bei Aufrufen von AllocateDmaBuffer und FreeDmaBuffer muss sich die DMA-Engine im Streamzurücksetzungszustand befinden. Die DMA-Engine befindet sich unmittelbar nach dem Aufruf von AllocateXxxDmaEngine im Zurücksetzungszustand. Um die DMA-Engine in den Ausführungszustand zu ändern, rufen Sie SetDmaEngineState auf.

Die FIFO-Größe ist die maximale Anzahl von Bytes, die die DMA-Engine in ihrem internen Puffer enthalten kann. Abhängig von der Hardwareimplementierung kann die FIFO-Größe einer DMA-Engine entweder statisch sein oder dynamisch mit Änderungen im Streamformat variieren. Weitere Informationen zur FIFO-Größe finden Sie in der Intel High Definition Audio Specification auf der Intel HD Audio-Website .

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

Ein zuvor zugeordneter DMA-Puffer wurde nicht freigegeben (durch Aufrufen von FreeDmaBuffer).
Der Stream 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 (zum Zeitpunkt der Pinerstellung) oder der SetFormat-Methode (nach dem Aufruf einer der AllocateXxxDmaEngine-Routinen in HD Audio DDI) auf. Weitere Informationen finden Sie unter IMiniportWavePci::NewStream und IMiniportWavePciStream::SetFormat.