PALLOCATE_CONTIGUOUS_DMA_BUFFER funzione di callback (hdaudio.h)

Articolo
02/07/2025

La routine AllocateContiguousDmaBuffer alloca un buffer DMA costituito da un singolo blocco contiguo di memoria fisica.

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

Sintassi

PALLOCATE_CONTIGUOUS_DMA_BUFFER PallocateContiguousDmaBuffer;

NTSTATUS PallocateContiguousDmaBuffer(
  [in]  PVOID _context,
  [in]  HANDLE Handle,
        ULONG RequestedBufferSize,
  [out] PVOID *DataBuffer,
  [out] PHDAUDIO_BUFFER_DESCRIPTOR *BdlBuffer
)
{...}

Parametri

[in] _context

Specifica il valore di contesto del membro context della struttura HDAUDIO_BUS_INTERFACE_BDL.

[in] Handle

Gestire l'identificazione del motore DMA. Questo valore di handle è stato ottenuto da una chiamata precedente a AllocateCaptureDmaEngine o AllocateRenderDmaEngine.

RequestedBufferSize

Specifica le dimensioni del buffer richieste in byte.

[out] DataBuffer

Recupera il buffer di dati. Questo parametro punta a una variabile PVOID allocata dal chiamante in cui la routine scrive l'indirizzo virtuale di sistema del buffer di dati.

[out] BdlBuffer

Recupera l'elenco dei descrittori del buffer (BDL). Questo parametro punta a una variabile PVOID allocata dal chiamante in cui la routine scrive l'indirizzo virtuale di sistema del file BDL. Le dimensioni di allocazione BDL sono esattamente una pagina di memoria e il file BDL inizia su un limite di pagina.

Valore restituito

AllocateContiguousDmaBuffer 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 a un livello di richiesta di interrupt (IRQL) 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 che si è verificato 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.

Osservazioni

La routine AllocateContiguousDmaBuffer viene utilizzata insieme alle routine SetupDmaEngineWithBdl e FreeContiguousDmaBuffer. Queste tre routine sono disponibili solo nella versione HDAUDIO_BUS_INTERFACE_BDL di HD Audio DDI. Questa DDI non include le routine di AllocateDmaBuffer e FreeDmaBuffer, mai usate insieme a AllocateContiguousDmaBuffer, SetupDmaEngineWithBdle FreeContiguousDmaBuffer. A differenza di 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. Per altre informazioni, vedere Differenze tra le due versioni DDI.

AllocateContiguousDmaBuffer alloca un buffer di dati per il motore DMA specificato. Alloca anche una pagina di memoria per il file BDL. A seconda dell'architettura del processore host, una dimensione di pagina tipica potrebbe essere di 4.096 o 8.192 byte. Il buffer di dati è costituito da un singolo blocco contiguo di memoria fisica.

Il parametro handle specifica il motore DMA che deve usare il buffer di dati e BDL. La routine alloca lo spazio di archiviazione che soddisfa i requisiti di dimensioni, allineamento e posizione del motore DMA.

L'archiviazione allocata dalla routine per il buffer di dati e BDL non è inizializzata. Il driver di funzione è responsabile della compilazione del file BDL prima di inviarlo alla routine SetupDmaEngineWithBdl. Il driver di funzione è anche responsabile della programmazione del codec per gestire i trasferimenti di dati e per riconoscere l'identificatore del flusso.

Per generare interrupt IOC a intervalli precisi, il driver di funzione potrebbe essere necessario dividere l'allocazione del buffer di dati in diversi frammenti di una determinata dimensione. Ogni frammento viene descritto da una voce BDL. Le dimensioni del frammento possono essere modificate per ottimizzare la frequenza di interruzione. In base alla specifica audio intel ad alta definizione (vedere il sito Web Intel HD Audio), ogni frammento deve iniziare su un limite di 128 byte, anche se tale requisito di allineamento si applica alla lunghezza del frammento. Pertanto, potrebbe esistere un divario tra la fine di un frammento e l'inizio della successiva. Quando si chiama SetupDmaEngineWithBdl, il driver di funzione deve specificare un valore per il parametro bufferSize che rappresenta la somma delle dimensioni dei singoli frammenti descritti dalle voci BDL. Questa dimensione sarà minore o uguale al numero di byte specificato nel parametro requestedBufferSize della routine AllocateContiguousDmaBuffer.

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

Durante le chiamate a AllocateContiguousDmaBuffer, SetupDmaEngineWithBdle FreeContiguousDmaBuffer, il motore DMA deve trovarsi nello stato del flusso di reimpostazione. Il motore DMA si trova nello stato di reimpostazione immediatamente dopo la chiamata a AllocateXxxDmaEngine. Per modificare lo stato di esecuzione del motore DMA, chiamare SetDmaEngineState.

Questa routine ha esito negativo e restituisce il codice di errore STATUS_INVALID_DEVICE_REQUEST in una delle circostanze seguenti: