PALLOCATE_RENDER_DMA_ENGINE funzione di callback (hdaudio.h)

Articolo
02/26/2024

La AllocateRenderDmaEngine routine alloca un motore DMA per un flusso di rendering.

Il tipo di puntatore della funzione per una AllocateRenderDmaEngine routine è definito come indicato di seguito.

Sintassi

PALLOCATE_RENDER_DMA_ENGINE PallocateRenderDmaEngine;

NTSTATUS PallocateRenderDmaEngine(
  [in]  PVOID _context,
  [in]  PHDAUDIO_STREAM_FORMAT StreamFormat,
  [in]  BOOLEAN Stripe,
  [out] PHANDLE Handle,
  [out] PHDAUDIO_CONVERTER_FORMAT ConverterFormat
)
{...}

Parametri

[in] _context

Specifica il valore di contesto dai membri Contesto delle strutture HDAUDIO_BUS_INTERFACE,HDAUDIO_BUS_INTERFACE_V2 o HDAUDIO_BUS_INTERFACE_BDL.

[in] StreamFormat

Specifica il formato di flusso richiesto. Questo parametro punta a una struttura allocata del chiamante di tipo HDAUDIO_STREAM_FORMAT che specifica un formato di dati per il flusso.

[in] Stripe

Specifica se abilitare il striping. Se TRUE, la routine abilita lo striping nei trasferimenti DMA. Se FALSE, il striping è disabilitato.

[out] Handle

Recupera l'handle nel motore DMA. Questo parametro punta a una variabile HANDLE allocata dal chiamante in cui la routine scrive un handle che identifica il motore DMA.

[out] ConverterFormat

Recupera il formato del convertitore. Questo parametro punta a una struttura allocata del chiamante di tipo HDAUDIO_CONVERTER_FORMAT in cui la routine scrive il formato codificato.

Valore restituito

AllocateRenderDmaEngine restituisce STATUS_SUCCESS se la chiamata riesce a riservare un motore DMA. In caso contrario, la routine restituisce un codice di errore appropriato. La tabella seguente mostra alcuni dei possibili codici di errore restituiti.

Codice restituito	Descrizione
STATUS_BUFFER_TOO_SMALL	Indica che il motore DMA non è in grado di allocare un'archiviazione FIFO interna sufficiente per supportare il formato di flusso richiesto.
STATUS_INSUFFICIENT_RESOURCES	Indica che nessun motore DMA è disponibile o la richiesta supera le risorse di larghezza di banda disponibili.
STATUS_INVALID_PARAMETER	Indica che uno dei valori dei parametri non è corretto (valore del parametro non valido o puntatore non valido).

Commenti

Questa routine alloca un motore DMA di rendering e specifica il formato dati per il flusso. In caso di esito positivo, la routine restituisce un handle usato successivamente dal chiamante per identificare il motore DMA.

La AllocateRenderDmaEngine routine riserva risorse hardware (motore DMA) ma non configura l'hardware DMA. Dopo aver chiamato questa routine per riservare un motore DMA, un driver di funzione deve assegnare un buffer DMA al motore DMA e configurare il motore per usare il buffer:

Se si usa la versione HDAUDIO_BUS_INTERFACE di HD Audio DDI, il driver di funzione chiama la routine AllocateDmaBuffer per avere il driver del bus audio HD allocare un buffer di dati per i trasferimenti DMA e configurare il motore DMA per usare il buffer.
Se si usa la versione HDAUDIO_BUS_INTERFACE_BDL di DDI, il driver di funzione chiama AllocateContiguousDmaBuffer per allocare il buffer DMA e chiama la routine SetupDmaEngineWithBdl per configurare il motore DMA per usare il buffer.

Il parametro streamFormat specifica il formato di dati per il flusso di acquisizione. Dopo la chiamata a AllocateRenderDmaEngine, il formato del flusso può essere modificato chiamando ChangeBandwidthAllocation.

Il parametro striping specifica se il motore DMA usa lo striping per velocizzare i trasferimenti di dati. Per altre informazioni, vedere Striping.

Tramite il parametro handle, la routine restituisce un handle usato dal chiamante per identificare il motore DMA allocato nelle chiamate successive a AllocateDmaBuffer, ChangeBandwidthAllocation, FreeDmaBuffer, SetupDmaEngineWithBdl e SetDmaEngineState. Il driver di funzione libera l'handle chiamando FreeDmaEngine.

Tramite il parametro ConverterFormat , la routine restituisce un valore descrittore di flusso che il chiamante può usare per programmare i convertitori di output. La routine codifica le informazioni dal parametro streamFormat in un intero a 16 bit. Per altre informazioni, vedere HDAUDIO_CONVERTER_FORMAT.

Immediatamente dopo una chiamata riuscita a AllocateRenderDmaEngine, il motore DMA si trova nello stato del flusso di reimpostazione. Prima di chiamare SetDmaEngineState per modificare il motore DMA in esecuzione, sospeso o arrestato, il client deve prima allocare un buffer DMA per il motore.

Un driver audio WDM chiama AllocateRenderDmaEngine al momento della creazione dei pin durante l'esecuzione del metodo NewStream , ad esempio, vedere IMiniportWavePci::NewStream.