PALLOCATE_CAPTURE_DMA_ENGINE funzione di callback (hdaudio.h)

Articolo
02/29/2024

La AllocateCaptureDmaEngine routine alloca un motore DMA per un flusso di acquisizione.

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

Sintassi

PALLOCATE_CAPTURE_DMA_ENGINE PallocateCaptureDmaEngine;

NTSTATUS PallocateCaptureDmaEngine(
  [in]  PVOID _context,
  [in]  UCHAR CodecAddress,
  [in]  PHDAUDIO_STREAM_FORMAT StreamFormat,
  [out] PHANDLE Handle,
  [out] PHDAUDIO_CONVERTER_FORMAT ConverterFormat
)
{...}

Parametri

[in] _context

Specifica il valore di contesto dal membro Context della struttura HDAUDIO_BUS_INTERFACE, HDAUDIO_BUS_INTERFACE_V2 o HDAUDIO_BUS_INTERFACE_BDL .

[in] CodecAddress

Specifica un indirizzo codec. Questo parametro identifica i dati seriali nella riga (SDI) su cui il codec fornisce i dati di acquisizione al controller del bus audio HD. Un controller bus con n pin SDI può supportare fino a n codec con indirizzi compresi tra 0 e n-1.

[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.

[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

AllocateCaptureDmaEngine restituisce STATUS_SUCCESS se la chiamata riesce a riservare un motore DMA. In caso contrario, i valori restituiti possibili includono i codici di errore nella tabella seguente.

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 del 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 acquisizione 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 AllocateCaptureDmaEngine 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 l'uso del buffer:

Se si usa la versione HDAUDIO_BUS_INTERFACE di HD Audio DDI, il driver di funzione chiama la routine AllocateDmaBuffer per fare in modo che il driver del bus HD Audio allochi 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 di dati per il flusso di acquisizione. Dopo la chiamata a AllocateCaptureDmaEngine, il formato del flusso può essere modificato chiamando ChangeBandwidthAllocation.

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 input. 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 AllocateCaptureDmaEngine, il motore DMA si trova nello stato del flusso di reimpostazione. Prima di chiamare SetDmaEngineState per modificare il motore DMA nello stato in esecuzione, sospeso o arrestato, il client deve prima allocare un buffer DMA per il motore.

Un driver audio WDM (Windows Driver Model) chiama AllocateCaptureDmaEngine al momento della creazione del pin durante l'esecuzione del metodo NewStream (ad esempio, vedere IMiniportWavePci::NewStream).