PSETUP_DMA_ENGINE_WITH_BDL Rückruffunktion (hdaudio.h)

Artikel
02/07/2025

Die SetupDmaEngineWithBdl Routine richtet ein DMA-Modul 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

Behandeln, das das DMA-Modul identifiziert. Dieser Handlewert wurde aus einem vorherigen Aufruf von AllocateCaptureDmaEngine oder AllocateRenderDmaEngineabgerufen.

[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 das DMA-Modul diesen Deskriptor verarbeitet hat, wird er wieder in den ersten Deskriptor in der Liste umgebrochen und die Verarbeitung fortgesetzt. Wenn die BDL n Deskriptoren enthält, werden sie 0 bis n-1 nummeriert. Der wert lvi muss mindestens 1 sein; Mit anderen Worten, die BDL muss mindestens zwei gültige Einträge enthalten, bevor das DMA-Modul den Betrieb starten kann.

[in] Isr

Funktionszeiger auf den ISR des Aufrufers. Wenn der Aufrufer das Interrupt-on-Completion-Bit (IOC) in einem oder mehreren Pufferdeskriptoren in der BDL festlegt, ruft der HD-Audiobustreiber den ISR jedes Mal auf, wenn ein IOC-Interrupt im Datenstrom 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 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 UINT-Variable, in die die FIFO-Größe von der Routine geschrieben wird.

Rückgabewert

SetupDmaEngineWithBdl 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_INVALID_HANDLE	Gibt an, dass der Handle Parameterwert ungültig ist.
STATUS_INVALID_PARAMETER	Gibt an, dass einer der Parameterwerte falsch ist (ungültiges Zeiger- oder ungültiges Datenstromformat).
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 das DMA-Gerät oder der DMA-Puffer nicht zugeordnet ist oder sich der Datenstrom nicht im Reset-Zustand befindet.

Bemerkungen

Die SetupDmaEngineWithBdl Routine wird in Verbindung mit der AllocateContiguousDmaBuffer und FreeContiguousDmaBuffer Routinen 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 AllocateDmaBuffer und FreeDmaBuffer Routinen, die nie in Verbindung mit AllocateContiguousDmaBuffer, SetupDmaEngineWithBdlund FreeContiguousDmaBufferverwendet werden. Im Gegensatz zu SetupDmaEngineWithBdl, das das DMA-Modul für die Verwendung eines zuvor zugewiesenen DMA-Puffers konfiguriert, AllocateDmaBuffer beide einen DMA-Puffer zuordnet und das DMA-Modul für die Verwendung des Puffers konfiguriert.

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

Sowohl die BDL als auch der darin beschriebene Pufferspeicher müssen während DMA-Vorgängen gültig bleiben. Nach dem Aufruf von SetupDmaEngineWithBdlmuss der BDL- und Pufferspeicher gültig bleiben, solange das DMA-Modul den Puffer weiterhin verwendet. Das DMA-Modul verwendet den Puffer, bis der Funktionstreiber den Puffer durch Aufrufen SetupDmaEngineWithBdl erneut aufruft oder das DMA-Modul durch Aufrufen von FreeDmaEnginefreisetzt. Der Funktionstreiber ist für das Aufrufen von FreeContiguousDmaBuffer verantwortlich, um den Puffer und die BDL frei zu geben, wenn sie nicht mehr benötigt werden.

Beim Zuweisen des Speichers 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 von der BDL angegeben werden. Daher sollten nur Kunden mit bedeutendem Wissen über den Buscontroller und die Systemhardware die SetupDmaEngineWithBdl Routine verwenden.

Vor dem Aufrufen SetupDmaEngineWithBdl- zum Konfigurieren eines DMA-Moduls muss der Client AllocateCaptureDmaEngine oder AllocateRenderDmaEngine- aufrufen, um das DMA-Modul zuzuweisen. Der Handle-Parameter ist der Wert, der aus dem vorherigen Aufruf abgerufen wird, um XxxDmaEngine zuzuweisen.

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

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

Nach dem Aufruf von SetupDmaEngineWithBdlbefindet sich das DMA-Modul im Zustand "Zurücksetzen". Rufen Sie SetDmaEngineStateauf, um das DMA-Modul zu starten.

Parameter isr gibt den ISR an, den der HD-Audiobustreiber bei jedem Auftreten eines IOC-Interrupts im Datenstrom aufrufen soll. 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-Audiobustreiber 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 Streamstatusregister des HD-Audiocontrollers, die den Grund für den Interrupt angeben. Die folgende Tabelle zeigt die Bedeutung der einzelnen Bits in interruptBitMask.

Bitnummern	Bedeutung
31:5	Unbenutzt.
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 einen Unterlauf für einen Eingabedatenstrom), legt der HD-Audiocontroller das FIFOE-Bit auf 1 fest.
2	Pufferabschluss-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	Unbenutzt.

Der HD-Audiobustreiber 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 festzustellen, ob ein Datenstromfehler aufgetreten ist. Weitere Informationen zu den in der vorherigen Tabelle gezeigten Unterbrechungsstatusbits finden Sie in der Beschreibung des Datenstromstatusregisters in der Intel High Definition Audio Specification.

Die FIFO-Größe ist die maximale Anzahl von Bytes, die das DMA-Modul jederzeit 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.

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