PSETUP_DMA_ENGINE_WITH_BDL Rückruffunktion (hdaudio.h)

Artikel
02/29/2024

Die SetupDmaEngineWithBdl-Routine richtet eine DMA-Engine ein, um einen vom Aufrufer zugewiesenen DMA-Puffer zu verwenden.

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

Syntax

PSETUP_DMA_ENGINE_WITH_BDL PsetupDmaEngineWithBdl;

NTSTATUS PsetupDmaEngineWithBdl(
  [in]  PVOID _context,
  [in]  HANDLE Handle,
  [in]  ULONG BufferLength,
  [in]  ULONG Lvi,
  [in]  PHDAUDIO_BDL_ISR Isr,
  [in]  PVOID Context,
  [out] PUCHAR StreamId,
  [out] PULONG FifoSize
)
{...}

Parameter

[in] _context

Gibt den Kontextwert aus dem Context-Member der HDAUDIO_BUS_INTERFACE_BDL-Struktur an.

[in] Handle

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

[in] BufferLength

Die Länge des Puffers.

[in] Lvi

Gibt den letzten gültigen Index (LVI) an. Dieser Parameter enthält den Index für den letzten gültigen Pufferdeskriptor in der BDL. Nachdem die DMA-Engine diesen Deskriptor verarbeitet hat, wird der erste Deskriptor in der Liste umgebrochen und die Verarbeitung fortgesetzt. Wenn die BDL n-Deskriptoren enthält, sind sie 0 bis n-1 nummeriert. Der lvi-Wert muss mindestens 1 sein. Anders ausgedrückt: Die BDL muss mindestens zwei gültige Einträge enthalten, bevor die DMA-Engine den Betrieb aufnehmen kann.

[in] Isr

Funktionszeiger auf den ISR des Aufrufers. Wenn der Aufrufer das IOC-Bit (Interrupt-On-Completion) in mindestens einem der Pufferdeskriptoren in der BDL festlegt, ruft der HD Audio-Bustreiber den ISR jedes Mal auf, wenn ein IOC-Interrupt im Stream auftritt. Dieser Parameter ist ein Funktionszeiger vom Typ HDAUDIO_BDL_ISR, der im folgenden Abschnitt Hinweise definiert ist.

[in] Context

Der Kontext.

[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 UINT-Variable, in die die Routine die FIFO-Größe schreibt.

Rückgabewert

SetupDmaEngineWithBdl gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich ist. Andernfalls gibt die Routine einen entsprechenden 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 bei einer zu hohen IRQL ausgeführt wird.
STATUS_INVALID_HANDLE	Gibt an, dass der Wert des Handle-Parameters ungültig ist.
STATUS_INVALID_PARAMETER	Gibt an, dass einer der Parameterwerte falsch ist (fehlerhafter Zeiger oder ungültiges Streamformat).
STATUS_DEVICE_NOT_READY	Gibt an, dass für die 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 das DMA-Gerät oder der DMA-Puffer nicht zugeordnet ist oder sich der Stream nicht im Zustand Zurücksetzen befindet.

Hinweise

Die SetupDmaEngineWithBdl-Routine wird in Verbindung mit den Routinen AllocateContiguousDmaBuffer und FreeContiguousDmaBuffer verwendet. Diese drei Routinen sind nur in der HDAUDIO_BUS_INTERFACE_BDL Version des HD Audio DDI verfügbar. Dieser DDI enthält 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 zugewiesenen DMA-Puffers konfiguriert, weist AllocateDmaBuffer sowohl einen DMA-Puffer zu und konfiguriert die DMA-Engine für die Verwendung des Puffers.

Der Aufrufer muss AllocateContiguousDmaBuffer aufrufen, um Speicher im Systemspeicher sowohl für den DMA-Puffer als auch für die BDL zuzuweisen, die die seiten des physischen Arbeitsspeichers im Puffer beschreibt. Die BDL-Einträge müssen sich im physisch zusammenhängenden Arbeitsspeicher befinden. Der BDL- und Pufferspeicher müssen die Ausrichtungsanforderungen erfüllen, die in der Intel High Definition Audio Specification (siehe Intel HD Audio-Website ) beschrieben sind.

Sowohl die BDL als auch der darin beschriebene Pufferspeicher müssen während DMA-Vorgängen gültig bleiben. Nach dem Aufruf von SetupDmaEngineWithBdl müssen die BDL und der Pufferspeicher gültig bleiben, solange die DMA-Engine den Puffer weiterhin verwendet. Die DMA-Engine verwendet den Puffer, bis der Funktionstreiber den Puffer durch erneutes Aufrufen von SetupDmaEngineWithBdl ersetzt oder die DMA-Engine durch Aufruf von FreeDmaEngine frei gibt. Der Funktionstreiber ist dafür verantwortlich , FreeContiguousDmaBuffer aufzurufen, um den Puffer und die BDL freizusetzen, wenn sie nicht mehr benötigt werden.

Bei der Zuweisung von Arbeitsspeicher für den Puffer muss der Aufrufer alle Hardwareeinschränkungen für die Adresse, Länge und Ausrichtung der physisch zusammenhängenden Speicherblöcke erfüllen, die die BDL angibt. Daher sollten nur Clients mit wichtigen Kenntnissen des Buscontrollers und der Systemhardware die SetupDmaEngineWithBdl-Routine verwenden.

Vor dem Aufrufen von SetupDmaEngineWithBdl zum Konfigurieren einer DMA-Engine muss der Client AllocateCaptureDmaEngine oder AllocateRenderDmaEngine aufrufen, um die DMA-Engine zuzuweisen. Der Handle-Parameter ist der Wert, der aus dem vorherigen Aufruf von Allocate XxxDmaEngine abgerufen wurde.

Der Aufrufer ist für die Programmierung des Codecs verantwortlich, um die Datenübertragungen zu verwalten und den Streambezeichner zu erkennen.

Ein WDM-Audiotreiber ruft diese Routine während der Anhefterstellung während der Ausführung seiner NewStream-Methode auf (z. B. siehe IMiniportWavePci::NewStream).

Nach dem Aufruf von SetupDmaEngineWithBdl befindet sich die DMA-Engine im Status Zurücksetzen. Um die DMA-Engine zu starten, rufen Sie SetDmaEngineState auf.

Parameter isr gibt die ISR an, die der HD Audio-Bustreiber jedes Mal aufrufen soll, wenn ein IOC-Interrupt im Stream auftritt. Dieser Parameter ist ein Funktionszeiger vom Typ HDAUDIO_BDL_ISR, der wie folgt definiert ist:

typedef void
  (*PHDAUDIO_BDL_ISR)
    (IN VOID *Context, IN ULONG InterruptBitMask);

Der HD Audio-Bustreiber ruft den ISR mit demselben Kontextwert auf, den der Client im Kontextparameter des vorherigen SetupDmaEngineWithBdl-Aufrufs angegeben hat. Der interruptBitMask-Parameter enthält die Bits aus dem Stream des HD-Audiocontrollergeräts status Register, die den Grund für den Interrupt angeben. Die folgende Tabelle zeigt die Bedeutung der einzelnen Bits in interruptBitMask.

Bitzahlen	Bedeutung
31:5	Nicht verwendet.
4	Deskriptorfehler (DESE). Wenn beim Abrufen eines Pufferdeskriptors ein Fehler auftritt, legt der HD-Audiocontroller das DESE-Bit auf 1 fest.
3	FIFO-Fehler (FIFOE). Wenn ein FIFO-Fehler auftritt (ein Überlauf für einen Ausgabedatenstrom oder eine Unterausführung für einen Eingabedatenstrom), legt der HD-Audiocontroller das FIFOE-Bit auf 1 fest.
2	Puffervervollständigungs-Interruptstatus (BCIS). Wenn das IOC-Bit im Befehlsbyte des Pufferdeskriptors auf 1 festgelegt ist, legt der HD-Audiocontroller das BCIS-Bit auf 1 fest, nachdem das letzte Beispiel eines Puffers verarbeitet wurde.
1:0	Nicht verwendet.

Der HD Audio-Bustreiber legt die nicht verwendeten Bits auf Null fest. Anstatt davon auszugehen, dass ein IOC-Interrupt aufgetreten ist, muss der ISR immer den interruptBitMask-Parameter überprüfen, um zu ermitteln, ob ein Streamfehler aufgetreten ist. Weitere Informationen zu den Interrupt-status Bits, die in der obigen Tabelle gezeigt werden, finden Sie in der Beschreibung des Stream-status registers in der Intel High Definition Audio Specification.

Die FIFO-Größe ist die maximale Anzahl von Bytes, die die DMA-Engine jederzeit 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 unter Intel High Definition Audio Specification.

Der Aufrufer muss den Pufferspeicher und die BDL aus dem nicht auslagerten Pool zuordnen.