PALLOCATE_CONTIGUOUS_DMA_BUFFER Rückruffunktion (hdaudio.h)
Die AllocateContiguousDmaBuffer Routine weist einen DMA-Puffer zu, der aus einem einzelnen zusammenhängenden Block des physischen Speichers besteht.
Der Funktionszeigertyp für eine AllocateContiguousDmaBuffer Routine wird 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 Context Member der HDAUDIO_BUS_INTERFACE_BDL Struktur an.
[in] Handle
Behandeln Sie die Identifizierung des DMA-Moduls. Dieser Handlewert wurde aus einem vorherigen Aufruf von AllocateCaptureDmaEngine oder AllocateRenderDmaEngineabgerufen.
RequestedBufferSize
Gibt die angeforderte Puffergröße in Byte an.
[out] DataBuffer
Ruft den Datenpuffer ab. Dieser Parameter verweist auf eine aufrufergeteilte PVOID-Variable, in die die Routine die virtuelle Systemadresse des Datenpuffers schreibt.
[out] BdlBuffer
Ruft die Pufferdeskriptorliste (BDL) ab. Dieser Parameter verweist auf eine aufrufergeteilte PVOID-Variable, in die die Routine die virtuelle Systemadresse der BDL schreibt. Die BDL-Zuordnungsgröße ist genau eine Speicherseite, und die BDL beginnt auf 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ückgabestatuscodes aufgeführt.
| Rückgabecode | Beschreibung |
|---|---|
|
Gibt an, dass der Aufrufer auf einer Interruptanforderungsebene (IRQL) ausgeführt wird, die zu hoch ist. |
|
Gibt an, dass die Pufferzuweisung fehlgeschlagen ist. |
|
Gibt an, dass der Handle-Parameterwert ungültig ist. |
|
Gibt an, dass einer der Parameterwerte falsch ist (ungültiger Zeiger). |
|
Gibt an, dass das Zeitlimit für die Hardwareprogrammierung eingestellt ist. Wenn dies geschieht, befindet sich die Hardware möglicherweise in einem kompromittierten Zustand. |
|
Gibt an, dass sich der Datenstrom nicht im Zurücksetzungszustand befindet oder dass bereits ein Puffer für das DMA-Modul zugeordnet ist. |
Bemerkungen
Die AllocateContiguousDmaBuffer Routine wird in Verbindung mit den SetupDmaEngineWithBdl 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 so konfiguriert, dass ein zuvor zugewiesener DMA-Puffer verwendet wird, AllocateDmaBuffer beide einen DMA-Puffer zuweisen und das DMA-Modul so konfiguriert, dass der Puffer verwendet wird. Weitere Informationen finden Sie unter Unterschiede zwischen den beiden DDI-Versionen.
AllocateContiguousDmaBuffer weist einen Datenpuffer für das angegebene DMA-Modul zu. Außerdem wird eine Speicherseite für die BDL zugewiesen. Je nach Hostprozessorarchitektur kann eine typische Seitengröße 4.096 oder 8.192 Bytes betragen. Der Datenpuffer besteht aus einem einzelnen zusammenhängenden Block des physischen Speichers.
Der Handleparameter gibt das DMA-Modul an, das den Datenpuffer und BDL verwendet. Die Routine weist Speicher zu, der die Anforderungen an Größe, Ausrichtung und Position des DMA-Moduls erfüllt.
Der Speicher, den die Routine für den Datenpuffer zuweist, und BDL wird nicht initialisiert. Der Funktionstreiber ist dafür verantwortlich, die BDL auszufüllen, bevor er 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 Datenstrombezeichner zu erkennen.
Um IOC-Unterbrechungen in genauen Intervallen zu generieren, kann der Funktionstreiber erforderlich sein, um die Datenpufferzuordnung in mehrere Fragmente einer bestimmten Größe aufzuteilen. Jedes Fragment wird durch einen BDL-Eintrag beschrieben. Die Fragmentgröße kann angepasst werden, um die Unterbrechungsrate zu optimieren. Gemäß der Intel High Definition Audio Specification (siehe die Intel HD Audio Website), muss jedes Fragment auf einer Grenze von 128 Byte beginnen, obwohl keine solche Ausrichtungsanforderung für die Länge des Fragments gilt. So könnte eine Lücke zwischen dem Ende eines Fragments und dem Anfang des nächsten bestehen. Beim Aufrufen SetupDmaEngineWithBdlmuss 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 der Bytes, die im AllocateContiguousDmaBufferrequestedBufferSize Parameter der AllocateContiguousDmaBuffer Routine angegeben sind.
Während der Lebensdauer eines DMA-Modulhandles können AllocateContiguousDmaBuffer nacheinander aufgerufen werden, um neue DMA-Puffer zuzuweisen. Vor dem Aufrufen von AllocateContiguousDmaBuffermüssen jedoch alle zuvor zugewiesenen DMA-Puffer zuerst durch Aufrufen FreeContiguousDmaBuffer-freigegeben werden.
Bei Aufrufen von AllocateContiguousDmaBuffer, SetupDmaEngineWithBdlund FreeContiguousDmaBuffermuss das DMA-Modul im Zustand "Datenstrom zurücksetzen" sein. Das DMA-Modul befindet sich unmittelbar nach dem Aufruf zum ZuweisenXxxDmaEngine im Zustand "Zurücksetzen". Um das DMA-Modul in den Ausführungszustand zu ändern, rufen Sie SetDmaEngineStateauf.
Diese Routine schlägt fehl und gibt fehlercode STATUS_INVALID_DEVICE_REQUEST in einem der folgenden Situationen zurück:
- Alle zuvor zugewiesenen DMA-Puffer wurden nicht freigegeben (durch Aufrufen von FreeContiguousDmaBuffer).
- Der Datenstrom befindet sich in einem anderen Zustand als "Zurücksetzen".
Anforderungen
| Anforderung | Wert |
|---|---|
| Zielplattform- | Desktop |
| Header- | hdaudio.h (einschließlich Hdaudio.h) |
| IRQL- | PASSIVE_LEVEL |