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

Artigo
02/07/2025

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

O tipo de ponteiro de função para uma rotina de AllocateRenderDmaEngine é 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 de Contexto das estruturas HDAUDIO_BUS_INTERFACE,HDAUDIO_BUS_INTERFACE_V2ou HDAUDIO_BUS_INTERFACE_BDL.

[in] StreamFormat

Especifica o formato de fluxo solicitado. Esse parâmetro aponta para uma estrutura alocada por 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 VERDADEIRO, 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 DMA. Esse parâmetro aponta para uma variável HANDLE alocada por chamador na qual a rotina grava um identificador que identifica o mecanismo DMA.

[out] ConverterFormat

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

Valor de retorno

AllocateRenderDmaEngine retornará STATUS_SUCCESS se a chamada tiver êxito em reservar um mecanismo de DMA. 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 consegue 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 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 incorreto).

Observações

Essa rotina aloca um mecanismo de DMA de renderização e especifica o formato de dados para o fluxo. Se bem-sucedida, a rotina gera um identificador que o chamador usa posteriormente para identificar o mecanismo de DMA.

O AllocateRenderDmaEngine rotina reserva recursos de hardware (o mecanismo de DMA), mas não configura o hardware de DMA. Depois de chamar essa rotina para reservar um mecanismo de DMA, um driver de função deve atribuir um buffer de DMA ao mecanismo 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 do DDI, o driver de função chamará AllocateContiguousDmaBuffer para alocar o buffer DMA e chamará a rotina de SetupDmaEngineWithBdl para configurar o mecanismo 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 especifica se o mecanismo de DMA deve usar a distribuição para acelerar as transferências de dados. Para obter mais informações, consulte Striping.

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, SetupDmaEngineWithBdle 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 do fluxo de redefinição. Antes de chamar SetDmaEngineState para alterar o mecanismo 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).