PALLOCATE_RENDER_DMA_ENGINE funzione di callback (hdaudio.h)

Articolo
02/07/2025

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

Il tipo di puntatore di funzione per una routine AllocateRenderDmaEngine è definito come segue.

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 dalle strutture di Context delle strutture HDAUDIO_BUS_INTERFACE,HDAUDIO_BUS_INTERFACE_V2o HDAUDIO_BUS_INTERFACE_BDL.

[in] StreamFormat

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

[in] Stripe

Specifica se abilitare lo striping. Se TRUE, la routine abilita lo striping nei trasferimenti DMA. Se FALSE, lo 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 dal 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 prenotare un motore DMA. In caso contrario, la routine restituisce un codice di errore appropriato. La tabella seguente illustra alcuni dei possibili codici di errore restituiti.

Codice restituito	Descrizione
STATUS_BUFFER_TOO_SMALL	Indica che il motore DMA non è in grado di allocare spazio di archiviazione FIFO interno sufficiente per supportare il formato di flusso richiesto.
STATUS_INSUFFICIENT_RESOURCES	Indica che nessun motore DMA è disponibile o la richiesta supera le risorse della 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).

Osservazioni

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

La routine AllocateRenderDmaEngine riserva risorse hardware (il 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 l'uso del buffer:

Se si usa la versione HDAUDIO_BUS_INTERFACE di HD Audio DDI, il driver della funzione chiama la routine AllocateDmaBuffer per fare in modo che il driver del bus audio HD alloca un buffer di dati per i trasferimenti DMA e configuri il motore DMA per l'uso del buffer.
Se si usa la versione HDAUDIO_BUS_INTERFACE_BDL di DDI, il driver della funzione chiama AllocateContiguousDmaBuffer per allocare il buffer DMA e chiama la routine SetupDmaEngineWithBdl per configurare il motore DMA per l'uso del buffer.

Il parametro streamFormat specifica il formato dei 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 deve usare 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, SetupDmaEngineWithBdle 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 numero 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 sullo stato in esecuzione, sospeso o arrestato, il client deve prima allocare un buffer DMA per il motore.

Un driver audio WDM chiama AllocateRenderDmaEngine in fase di creazione del pin durante l'esecuzione del relativo metodo NewStream (ad esempio, vedere IMiniportWavePci::NewStream).