PALLOCATE_DMA_BUFFER_WITH_NOTIFICATION funzione di callback (hdaudio.h)

Articolo
02/26/2024

La AllocateDmaBufferWithNotification routine alloca un buffer di dati nella memoria di sistema per un motore DMA.

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

Sintassi

PALLOCATE_DMA_BUFFER_WITH_NOTIFICATION PallocateDmaBufferWithNotification;

NTSTATUS PallocateDmaBufferWithNotification(
  [in]  PVOID _context,
  [in]  HANDLE Handle,
  [in]  ULONG NotificationCount,
  [in]  SIZE_T RequestedBufferSize,
  [out] PMDL *BufferMdl,
  [out] PSIZE_T AllocatedBufferSize,
        PSIZE_T OffsetFromFirstPage,
  [out] PUCHAR StreamId,
  [out] PULONG FifoSize
)
{...}

Parametri

[in] _context

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

[in] Handle

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

[in] NotificationCount

Specifica il numero di notifiche necessarie, in base alla progressione DMA attraverso il buffer audio. Attualmente è supportato un valore pari a 1 o 2. Quando il valore è 1, ogni evento di notifica registrato viene segnalato ogni volta che il buffer audio ciclico viene completato e DMA esegue il wrapping all'inizio. Quando il valore è 2, tutti gli eventi di notifica registrati vengono notificati quando DMA passa il punto intermedio del buffer audio e alla fine (o il punto di wrapping).

[in] RequestedBufferSize

Specifica le dimensioni del buffer richieste, in byte.

[out] BufferMdl

Recupera le pagine di memoria fisica che contengono il buffer allocato. Questo parametro punta a una variabile allocata dal chiamante che è un puntatore a un elenco di descrittori di memoria (PMDL). Questa routine scrive un puntatore che descrive il buffer dell'elenco dei descrittori di memoria nella variabile PMDL.

[out] AllocatedBufferSize

Recupera le dimensioni del buffer allocate, in byte. Questo parametro punta a una variabile allocata dal chiamante SIZE_T in cui la routine scrive le dimensioni del buffer allocato.

OffsetFromFirstPage

[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 dalla routine al flusso.

[out] FifoSize

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

Valore restituito

La AllocateDmaBufferWithNotification routine 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 errore restituiti.

Codice restituito	Descrizione
STATUS_UNSUCCESSFUL	Indica che il chiamante è in esecuzione in un runtime di integrazione troppo elevato.
STATUS_INSUFFICIENT_RESOURCES	Indica che l'allocazione del buffer non è riuscita.
STATUS_INVALID_HANDLE	Indica che il valore del parametro handle non è valido.
STATUS_INVALID_PARAMETER	Indica che uno dei valori dei parametri non è corretto (puntatore 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 flusso non è nello stato di reimpostazione o che un buffer è già allocato per il motore DMA e non è stato ancora liberato.

Commenti

La AllocateDmaBufferWithNotification routine viene utilizzata insieme alla routine FreeDmaBufferWithNotification . Queste due routine sono disponibili solo nella versione HDAUDIO_BUS_INTERFACE_V2 di HD Audio DDI. Diversamente da SetupDmaEngineWithBdl, che configura il motore DMA per l'uso di un buffer DMA allocato in precedenza, AllocateDmaBufferWithNotification alloca un buffer DMA e configura anche il motore DMA per l'uso del buffer.

Se il motore DMA non può usare un buffer delle dimensioni richieste nel parametro requestedBufferSize, la routine alloca un buffer il più vicino possibile alle dimensioni richieste.

Il driver di funzione per un codec audio o modem è responsabile della programmazione del codec per gestire i trasferimenti di dati e per riconoscere l'identificatore del flusso.

AllocateDmaBufferWithNotification restituisce un file MDL che elenca le pagine di memoria fisica che contengono il buffer. L'indirizzo di base del buffer coincide con l'inizio della prima pagina fisica nell'elenco.

Durante la durata di un handle del motore DMA, AllocateDmaBufferWithNotification può essere chiamato successivamente per allocare nuovi buffer DMA. Tuttavia, prima di chiamare AllocateDmaBufferWithNotification, qualsiasi buffer DMA allocato in precedenza deve essere liberato chiamando FreeDmaBufferWithNotification.

Durante le chiamate a AllocateDmaBufferWithNotification e FreeDmaBufferWithNotification, il motore DMA deve trovarsi nello stato del flusso di reimpostazione. Il motore DMA si trova nello stato del flusso di reimpostazione immediatamente dopo la chiamata a AllocateCaptureDmaEngine o AllocateRenderDmaEngine. Per modificare lo stato di esecuzione del motore DMA, chiamare SetDmaEngineState.

Le dimensioni FIFO sono il numero massimo di byte che il motore DMA può contenere nel buffer interno. 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.

In Windows Vista e versioni successive di Windows, un driver miniport WaveRT chiama questa routine quando riceve la richiesta di proprietà KSPROPERTY_RTAUDIO_BUFFER_WITH_NOTIFICATION .

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile in Windows Vista e versioni successive di Windows.
Piattaforma di destinazione	Desktop
Intestazione	hdaudio.h (include Hdaudio.h)
IRQL	PASSIVE_LEVEL.