funzione di callback PALLOCATE_DMA_BUFFER (hdaudio.h)

Articolo
02/26/2024

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

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

Sintassi

PALLOCATE_DMA_BUFFER PallocateDmaBuffer;

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

Parametri

[in] _context

Specifica il valore di contesto dai membri Context delle strutture HDAUDIO_BUS_INTERFACE e HDAUDIO_BUS_INTERFACE_V2 .

[in] Handle

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

[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 PMDL allocata dal chiamante in cui la routine scrive un puntatore in un elenco di descrittori di memoria (MDL) che descrive il buffer.

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

[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 ULONG allocata dal chiamante in cui la routine scrive le dimensioni FIFO.

Valore restituito

AllocateDmaBuffer 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_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.

Commenti

La AllocateDmaBuffer routine viene utilizzata insieme alla routine FreeDmaBuffer . Queste due routine sono disponibili solo nelle HDAUDIO_BUS_INTERFACE e nelle versioni HDAUDIO_BUS_INTERFACE_V2 di HD Audio DDI. Questa DDI non include le routine AllocateContiguousDmaBuffer, SetupDmaEngineWithBdl e FreeContiguousDmaBuffer , che non vengono mai usate in combinazione con AllocateDmaBuffer e FreeDmaBuffer. 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.

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.

La routine 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, AllocateDmaBuffer può essere chiamato successivamente per allocare nuovi buffer DMA. Tuttavia, prima di chiamare AllocateDmaBuffer, qualsiasi buffer DMA allocato in precedenza deve essere liberato chiamando FreeDmaBuffer.

Durante le chiamate a AllocateDmaBuffer e FreeDmaBuffer, 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.

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 nel sito Web Intel HD Audio .

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

Qualsiasi buffer DMA allocato in precedenza non è stato liberato (chiamando FreeDmaBuffer).
Il flusso è in uno stato diverso da reset.

In Windows Server 2003, Windows XP, Windows 2000 e Windows Me/98, un driver audio WDM chiama questa routine durante l'esecuzione del metodo NewStream (in fase di creazione del pin) o SetFormat (dopo aver chiamato una delle routine AllocateXxxDmaEngine in HD Audio DDI). Per altre informazioni, vedere IMiniportWavePci::NewStream e IMiniportWavePciStream::SetFormat.