PALLOCATE_RENDER_DMA_ENGINE função de retorno de chamada (hdaudio.h)

Artigo
08/07/2023

A AllocateRenderDmaEngine rotina aloca um mecanismo de AMD para um fluxo de renderização.

O tipo de ponteiro de função para uma AllocateRenderDmaEngine rotina é definido da seguinte maneira.

Sintaxe

PALLOCATE_RENDER_DMA_ENGINE PallocateRenderDmaEngine;

NTSTATUS PallocateRenderDmaEngine(
  [in]  PVOID _context,
  [in]  PHDAUDIO_STREAM_FORMAT StreamFormat,
  [in]  BOOLEAN Stripe,
  [out] PHANDLE Handle,
  [out] PHDAUDIO_CONVERTER_FORMAT ConverterFormat
)
{...}

Parâmetros

[in] _context

Especifica o valor de contexto dos membros Context das estruturas HDAUDIO_BUS_INTERFACE,HDAUDIO_BUS_INTERFACE_V2 ou HDAUDIO_BUS_INTERFACE_BDL.

[in] StreamFormat

Especifica o formato de fluxo solicitado. Esse parâmetro aponta para uma estrutura alocada pelo chamador do tipo HDAUDIO_STREAM_FORMAT que especifica um formato de dados para o fluxo.

[in] Stripe

Especifica se a distribuição deve ser habilitada. Se TRUE, a rotina habilita a distribuição nas transferências de DMA. Se FALSE, a distribuição será desabilitada.

[out] Handle

Recupera o identificador para o mecanismo de DMA. Esse parâmetro aponta para uma variável HANDLE alocada pelo chamador na qual a rotina grava um identificador que identifica o mecanismo de DMA.

[out] ConverterFormat

Recupera o formato do conversor. Esse parâmetro aponta para uma estrutura alocada pelo chamador do tipo HDAUDIO_CONVERTER_FORMAT na qual a rotina grava o formato codificado.

Retornar valor

AllocateRenderDmaEngine retornará STATUS_SUCCESS se a chamada for bem-sucedida na reserva de um mecanismo de AMD. Caso contrário, a rotina retornará um código de erro apropriado. A tabela a seguir mostra alguns dos possíveis códigos de erro de retorno.

Código de retorno	Descrição
STATUS_BUFFER_TOO_SMALL	Indica que o mecanismo de DMA não pode alocar armazenamento FIFO interno suficiente para dar suporte ao formato de fluxo solicitado.
STATUS_INSUFFICIENT_RESOURCES	Indica que nenhum mecanismo de DMA está disponível ou que a solicitação excede os recursos de largura de banda disponíveis.
STATUS_INVALID_PARAMETER	Indica que um dos valores de parâmetro está incorreto (valor de parâmetro inválido ou ponteiro inválido).

Comentários

Essa rotina aloca um mecanismo de DMA de renderização e especifica o formato de dados para o fluxo. Se tiver êxito, a rotina gerará um identificador que o chamador usará posteriormente para identificar o mecanismo de DMA.

A AllocateRenderDmaEngine rotina reserva recursos de hardware (o mecanismo de DMA), mas não configura o hardware de AMD. Depois de chamar essa rotina para reservar um mecanismo de DMA, um driver de função deve atribuir um buffer de DMA ao mecanismo de DMA e configurar o mecanismo para usar o buffer:

Se estiver usando a versão HDAUDIO_BUS_INTERFACE da DDI de áudio HD, o driver de função chamará a rotina AllocateDmaBuffer para que o driver do barramento de áudio HD aloque um buffer de dados para transferências de DMA e configure o mecanismo de DMA para usar o buffer.
Se estiver usando a versão HDAUDIO_BUS_INTERFACE_BDL da DDI, o driver de função chamará AllocateContiguousDmaBuffer para alocar o buffer DMA e chamará a rotina SetupDmaEngineWithBdl para configurar o mecanismo de DMA para usar o buffer.

O parâmetro streamFormat especifica o formato de dados para o fluxo de captura. Após a chamada para AllocateRenderDmaEngine, o formato do fluxo pode ser alterado chamando ChangeBandwidthAllocation.

O parâmetro stripe especifica se o mecanismo de DMA deve usar a distribuição para acelerar as transferências de dados. Para obter mais informações, consulte Distribuição.

Por meio do parâmetro handle, a rotina gera um identificador que o chamador usa para identificar o mecanismo de DMA alocado em chamadas subsequentes para AllocateDmaBuffer, ChangeBandwidthAllocation, FreeDmaBuffer, SetupDmaEngineWithBdl e SetDmaEngineState. O driver de função libera o identificador chamando FreeDmaEngine.

Por meio do parâmetro converterFormat , a rotina gera um valor de descritor de fluxo que o chamador pode usar para programar os conversores de saída. A rotina codifica as informações do parâmetro streamFormat em um inteiro de 16 bits. Para obter mais informações, consulte HDAUDIO_CONVERTER_FORMAT.

Imediatamente após uma chamada bem-sucedida para AllocateRenderDmaEngine, o mecanismo de DMA está no estado de fluxo de redefinição. Antes de chamar SetDmaEngineState para alterar o mecanismo de DMA para o estado em execução, pausado ou interrompido, o cliente deve primeiro alocar um buffer de DMA para o mecanismo.

Um driver de áudio WDM chama AllocateRenderDmaEngine no momento da criação do pin durante a execução de seu método NewStream (por exemplo, consulte IMiniportWavePci::NewStream).