PALLOCATE_CONTIGUOUS_DMA_BUFFER Rückruffunktion (hdaudio.h)

Artikel
08/07/2023

Die AllocateContiguousDmaBuffer Routine weist einen DMA-Puffer zu, der aus einem einzelnen zusammenhängenden Block physischen Speichers besteht.

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

Syntax

PALLOCATE_CONTIGUOUS_DMA_BUFFER PallocateContiguousDmaBuffer;

NTSTATUS PallocateContiguousDmaBuffer(
  [in]  PVOID _context,
  [in]  HANDLE Handle,
        ULONG RequestedBufferSize,
  [out] PVOID *DataBuffer,
  [out] PHDAUDIO_BUFFER_DESCRIPTOR *BdlBuffer
)
{...}

Parameter

[in] _context

Gibt den Kontextwert aus dem Kontextelement der HDAUDIO_BUS_INTERFACE_BDL-Struktur an.

[in] Handle

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

RequestedBufferSize

Gibt die angeforderte Puffergröße in Bytes an.

[out] DataBuffer

Ruft den Datenpuffer ab. Dieser Parameter verweist auf eine vom Aufrufer zugewiesene PVOID-Variable, in die die Routine die virtuelle Systemadresse des Datenpuffers schreibt.

[out] BdlBuffer

Ruft die Pufferdeskriptorliste (BDL) ab. Dieser Parameter verweist auf eine vom Aufrufer zugewiesene PVOID-Variable, in die die Routine die virtuelle Systemadresse der BDL schreibt. Die BDL-Zuordnungsgröße ist genau eine Speicherseite, und die BDL beginnt an einer Seitengrenze.

Rückgabewert

AllocateContiguousDmaBuffer 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 auf einer zu hohen Interruptanforderungsebene (IRQL) 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 AllocateContiguousDmaBuffer Routine wird in Verbindung mit den Routinen SetupDmaEngineWithBdl und FreeContiguousDmaBuffer verwendet. Diese drei Routinen sind nur in der HDAUDIO_BUS_INTERFACE_BDL Version des HD Audio DDI verfügbar. Dieser DDI umfasst nicht die Routinen AllocateDmaBuffer und FreeDmaBuffer , die nie in Verbindung mit AllocateContiguousDmaBuffer, SetupDmaEngineWithBdl und FreeContiguousDmaBuffer 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. Weitere Informationen finden Sie unter Unterschiede zwischen den beiden DDI-Versionen.

AllocateContiguousDmaBuffer weist einen Datenpuffer für die angegebene DMA-Engine zu. Außerdem wird eine Seite mit Arbeitsspeicher für die BDL zugeordnet. Abhängig von der Hostprozessorarchitektur kann eine typische Seitengröße 4.096 oder 8.192 Byte betragen. Der Datenpuffer besteht aus einem einzelnen zusammenhängenden Block des physischen Arbeitsspeichers.

Der handle-Parameter gibt die DMA-Engine an, die den Datenpuffer und die BDL verwenden soll. Die Routine weist Speicher zu, der die Anforderungen an Größe, Ausrichtung und Position der DMA-Engine erfüllt.

Der Speicher, den die Routine für den Datenpuffer und die BDL zuweist, wird nicht initialisiert. Der Funktionstreiber ist dafür verantwortlich, die BDL auszufüllen, bevor sie an die SetupDmaEngineWithBdl-Routine übermittelt wird. Der Funktionstreiber ist auch für die Programmierung des Codecs verantwortlich, um die Datenübertragungen zu verwalten und den Streambezeichner zu erkennen.

Um IOC-Interrupts in genauen Intervallen zu generieren, muss der Funktionstreiber möglicherweise die Datenpufferzuordnung in mehrere Fragmente einer bestimmten Größe aufteilen. Jedes Fragment wird durch einen BDL-Eintrag beschrieben. Die Fragmentgröße kann angepasst werden, um die Interruptrate zu optimieren. Gemäß der Intel High Definition Audio Specification (siehe Intel HD Audio-Website ) muss jedes Fragment an einer 128-Byte-Grenze beginnen, obwohl keine solche Ausrichtungsanforderung für die Länge des Fragments gilt. Daher könnte eine Lücke zwischen dem Ende eines Fragments und dem Anfang des nächsten bestehen. Beim Aufrufen von SetupDmaEngineWithBdl muss der Funktionstreiber einen Wert für den bufferSize-Parameter angeben, der die Summe der Größen der einzelnen Fragmente darstellt, die von den BDL-Einträgen beschrieben werden. Diese Größe ist kleiner oder gleich der Anzahl von Bytes, die im RequestedBufferSize-Parameter der AllocateContiguousDmaBuffer Routine angegeben ist.

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

Bei Aufrufen von AllocateContiguousDmaBuffer, SetupDmaEngineWithBdl und FreeContiguousDmaBuffer muss sich die DMA-Engine im Status "Stream zurücksetzen" 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.

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

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