PSETUP_DMA_ENGINE_WITH_BDL funzione di callback (hdaudio.h)

Articolo
02/26/2024

La routine SetupDmaEngineWithBdl configura un motore DMA per l'uso di un buffer DMA allocato dal chiamante.

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

Sintassi

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
)
{...}

Parametri

[in] _context

Specifica il valore di contesto dal membro Context della struttura HDAUDIO_BUS_INTERFACE_BDL .

[in] Handle

Handle che identifica il motore DMA. Questo valore handle è stato ottenuto da una chiamata precedente a AllocateCaptureDmaEngine o AllocateRenderDmaEngine.

[in] BufferLength

Lunghezza del buffer.

[in] Lvi

Specifica l'ultimo indice valido (LVI). Questo parametro contiene l'indice per l'ultimo descrittore di buffer valido nel file BDL. Dopo che il motore DMA elabora questo descrittore, esegue il wrapping al primo descrittore nell'elenco e continua l'elaborazione. Se il linguaggio BDL contiene n descrittori, vengono numerati da 0 a n-1. Il valore lvi deve essere almeno 1; in altre parole, il file BDL deve contenere almeno due voci valide prima che il motore DMA possa iniziare l'operazione.

[in] Isr

Puntatore a funzione all'ISR del chiamante. Se il chiamante imposta il bit di interrupt-on-completion (IOC) in uno o più descrittori di buffer nel BDL, il driver del bus audio HD chiama l'ISR ogni volta che si verifica un interrupt IOC nel flusso. Questo parametro è un puntatore a funzione di tipo HDAUDIO_BDL_ISR, definito nella sezione Osservazioni seguente.

[in] Context

Contesto.

[out] StreamId

Recupera l'identificatore del flusso. Questo parametro punta a una variabile UCHAR allocata dal chiamante in cui la routine scrive l'identificatore del flusso assegnato al flusso.

[out] FifoSize

Recupera le dimensioni FIFO del motore DMA in byte. Questo parametro punta a una variabile UINT allocata dal chiamante in cui la routine scrive le dimensioni FIFO.

Valore restituito

SetupDmaEngineWithBdl restituisce STATUS_SUCCESS se la chiamata ha esito positivo. In caso contrario, la routine restituisce un codice di errore appropriato. La tabella seguente illustra alcuni dei possibili codici di stato restituiti.

Codice restituito	Descrizione
STATUS_UNSUCCESSFUL	Indica che il chiamante è in esecuzione in un runtime di integrazione troppo elevato.
STATUS_INVALID_HANDLE	Indica che il valore del parametro handle non è valido.
STATUS_INVALID_PARAMETER	Indica che uno dei valori dei parametri non è corretto (un puntatore non valido o un formato di flusso non valido).
STATUS_DEVICE_NOT_READY	Indica il timeout della programmazione hardware. In questo caso, l'hardware potrebbe trovarsi in uno stato compromesso.
STATUS_INVALID_DEVICE_REQUEST	Indica che il dispositivo DMA o il buffer DMA non è allocato o che il flusso non è nello stato Reimposta.

Commenti

La routine SetupDmaEngineWithBdl viene utilizzata insieme alle routine AllocateContiguousDmaBuffer e FreeContiguousDmaBuffer . Queste tre routine sono disponibili solo nella versione HDAUDIO_BUS_INTERFACE_BDL di HD Audio DDI. Questa DDI non include le routine AllocateDmaBuffer e FreeDmaBuffer , che non vengono mai usate in combinazione con AllocateContiguousDmaBuffer, SetupDmaEngineWithBdl e FreeContiguousDmaBuffer. Diversamente da SetupDmaEngineWithBdl, che configura il motore DMA per l'uso di un buffer DMA allocato in precedenza, AllocateDmaBuffer alloca un buffer DMA e configura il motore DMA per l'uso del buffer.

Il chiamante deve chiamare AllocateContiguousDmaBuffer per allocare spazio di archiviazione nella memoria di sistema sia per il buffer DMA che per il BDL che descrive le pagine di memoria fisica nel buffer. Le voci BDL devono risiedere in memoria fisicamente contigue. La memoria BDL e buffer devono soddisfare i requisiti di allineamento descritti in Intel High Definition Audio Specification (vedere il sito Web Intel HD Audio ).

Sia il file BDL che la memoria buffer descritta devono rimanere validi durante le operazioni DMA. Dopo la chiamata a SetupDmaEngineWithBdl, la memoria BDL e buffer devono rimanere valide finché il motore DMA continua a usare il buffer. Il motore DMA usa il buffer finché il driver di funzione non sostituisce il buffer chiamando nuovamente SetupDmaEngineWithBdl o liberando il motore DMA chiamando FreeDmaEngine. Il driver di funzione è responsabile della chiamata a FreeContiguousDmaBuffer per liberare il buffer e BDL quando non sono più necessari.

Quando si alloca la memoria per il buffer, il chiamante deve soddisfare tutti i vincoli hardware per l'indirizzo, la lunghezza e l'allineamento dei blocchi di memoria fisicamente contigui specificati dal BDL. Pertanto, solo i client con una conoscenza significativa del controller del bus e dell'hardware di sistema devono usare la routine SetupDmaEngineWithBdl .

Prima di chiamare SetupDmaEngineWithBdl per configurare un motore DMA, il client deve chiamare AllocateCaptureDmaEngine o AllocateRenderDmaEngine per allocare il motore DMA. Il parametro handle è il valore ottenuto dalla chiamata precedente a Allocate XxxDmaEngine.

Il chiamante è responsabile della programmazione del codec per gestire i trasferimenti di dati e riconoscere l'identificatore del flusso.

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

Dopo la chiamata a SetupDmaEngineWithBdl, il motore DMA si trova nello stato Reset. Per avviare il motore DMA, chiamare SetDmaEngineState.

Il parametro isr specifica l'ISR che il driver del bus audio HD deve chiamare ogni volta che si verifica un interrupt IOC nel flusso. Questo parametro è un puntatore a funzione di tipo HDAUDIO_BDL_ISR, definito come:

typedef void
  (*PHDAUDIO_BDL_ISR)
    (IN VOID *Context, IN ULONG InterruptBitMask);

Il driver del bus audio HD chiama l'ISR con lo stesso valore di contesto specificato dal client nel parametro di contesto della chiamata setupDmaEngineWithBdl precedente. Il parametro interruptBitMask contiene i bit dal registro di stato del dispositivo del controller audio HD che indica il motivo dell'interrupt. La tabella seguente illustra il significato dei singoli bit in interruptBitMask.

Numeri di bit	Significato
31:5	Non utilizzato.
4	Errore del descrittore (DESE). Se si verifica un errore durante il recupero di un descrittore di buffer, il controller AUDIO HD imposta il bit DESE su 1.
3	Errore FIFO (FIFOE). Se si verifica un errore FIFO (un overrun in un flusso di output o un sottorun in un flusso di input), il controller AUDIO HD imposta il bit FIFOE su 1.
2	Stato di interruzione del completamento del buffer (BCIS). Se il bit IOC è impostato su 1 nel byte di comando del descrittore di buffer, il controller audio HD imposta il bit BCIS su 1 dopo l'elaborazione dell'ultimo campione di un buffer.
1:0	Non utilizzato.

Il driver del bus audio HD imposta i bit inutilizzati su zero. Invece di presupporre che si sia verificato un interrupt IOC, l'ISR deve sempre controllare il parametro interruptBitMask per determinare se si è verificato un errore del flusso. Per altre informazioni sui bit di stato di interruzione mostrati nella tabella precedente, vedere la descrizione dei registri di stato del flusso nella specifica audio intel ad alta definizione.

Le dimensioni FIFO sono il numero massimo di byte che il motore DMA può contenere nel buffer interno in qualsiasi momento. A seconda dell'implementazione hardware, le dimensioni FIFO di un motore DMA possono essere statiche o variare in modo dinamico con le modifiche nel formato del flusso. Per altre informazioni sulle dimensioni FIFO, vedere La specifica audio intel ad alta definizione.

Il chiamante deve allocare la memoria del buffer e BDL dal pool non di paging.