PALLOCATE_DMA_BUFFER_WITH_NOTIFICATION Rückruffunktion (hdaudio.h)

Artikel
08/07/2023

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

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

Syntax

PALLOCATE_DMA_BUFFER_WITH_NOTIFICATION PallocateDmaBufferWithNotification;

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

Parameter

[in] _context

Gibt den Kontextwert aus dem Context-Element der HDAUDIO_BUS_INTERFACE_V2-Struktur an.

[in] Handle

Ein Handle, das die DMA-Engine identifiziert. Dieser Handlewert wurde aus einem vorherigen Aufruf von AllocateCaptureDmaEngine oder AllocateRenderDmaEngine abgerufen.

[in] NotificationCount

Gibt die Anzahl der benötigten Benachrichtigungen basierend auf der DMA-Entwicklung durch den Audiopuffer an. Derzeit wird der Wert 1 oder 2 unterstützt. Wenn der Wert 1 ist, werden alle registrierten Benachrichtigungsereignisse jedes Mal signalisiert, wenn der zyklische Audiopuffer abgeschlossen ist, und DMA wird wieder an den Anfang umgebrochen. Wenn der Wert 2 ist, werden alle registrierten Benachrichtigungsereignisse benachrichtigt, wenn DMA den Mittelpunkt des Audiopuffers sowie am Ende (oder den Umbruchpunkt) übergibt.

[in] RequestedBufferSize

Gibt die angeforderte Puffergröße in Bytes an.

[out] BufferMdl

Ruft die physischen Speicherseiten ab, die den zugeordneten Puffer enthalten. Dieser Parameter verweist auf eine vom Aufrufer zugeordnete Variable, die ein Zeiger auf eine Speicherdeskriptorliste (PMDL) ist. Diese Routine schreibt einen Zeiger, der den Speicherdeskriptorlistenpuffer beschreibt, in die PMDL-Variable.

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

OffsetFromFirstPage

[out] StreamId

Ruft den Streambezeichner ab. Dieser Parameter verweist auf eine vom Aufrufer zugewiesene UCHAR-Variable, in die die Routine den Streambezeichner schreibt, den die Routine 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

Die AllocateDmaBufferWithNotification Routine 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ückgabefehlercodes 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 bei der Pufferzuordnung ein Fehler aufgetreten 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 bereits ein Puffer für die DMA-Engine zugeordnet ist und noch nicht freigegeben wurde.

Hinweise

Die AllocateDmaBufferWithNotification Routine wird zusammen mit der FreeDmaBufferWithNotification-Routine verwendet. Diese beiden Routinen sind nur in der HDAUDIO_BUS_INTERFACE_V2 Version von HD Audio DDI verfügbar. Im Gegensatz zu SetupDmaEngineWithBdl, das die DMA-Engine für die Verwendung eines zuvor zugeordneten DMA-Puffers konfiguriert, AllocateDmaBufferWithNotification ordnet einen DMA-Puffer zu und konfiguriert auch 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.

AllocateDmaBufferWithNotification 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, AllocateDmaBufferWithNotification um neue DMA-Puffer zuzuweisen. Vor dem Aufrufen AllocateDmaBufferWithNotificationvon muss jedoch jeder zuvor zugeordnete DMA-Puffer durch Aufrufen von FreeDmaBufferWithNotification freigegeben werden.

Während der Aufrufe von AllocateDmaBufferWithNotification und FreeDmaBufferWithNotification muss sich die DMA-Engine im Status "Stream zurücksetzen" befinden. Die DMA-Engine befindet sich unmittelbar nach dem Aufruf von AllocateCaptureDmaEngine oder AllocateRenderDmaEngine im Status zum Zurücksetzen des Datenstroms. 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.

In Windows Vista und höheren Versionen von Windows ruft ein WaveRT-Miniporttreiber diese Routine auf, wenn er die KSPROPERTY_RTAUDIO_BUFFER_WITH_NOTIFICATION-Eigenschaftsanforderung empfängt.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar in Windows Vista und späteren Windows-Versionen.
Zielplattform	Desktop
Kopfzeile	hdaudio.h (hdaudio.h einschließen)
IRQL	PASSIVE_LEVEL.