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

Artigo
08/07/2023

A AllocateCaptureDmaEngine rotina aloca um mecanismo de DMA para um fluxo de captura.

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

Sintaxe

PALLOCATE_CAPTURE_DMA_ENGINE PallocateCaptureDmaEngine;

NTSTATUS PallocateCaptureDmaEngine(
  [in]  PVOID _context,
  [in]  UCHAR CodecAddress,
  [in]  PHDAUDIO_STREAM_FORMAT StreamFormat,
  [out] PHANDLE Handle,
  [out] PHDAUDIO_CONVERTER_FORMAT ConverterFormat
)
{...}

Parâmetros

[in] _context

Especifica o valor de contexto do membro Context da estrutura HDAUDIO_BUS_INTERFACE, HDAUDIO_BUS_INTERFACE_V2 ou HDAUDIO_BUS_INTERFACE_BDL .

[in] CodecAddress

Especifica um endereço codec. Esse parâmetro identifica os dados serial na linha (SDI) na qual o codec fornece os dados de captura para o controlador de barramento de áudio HD. Um controlador de barramento com n pinos SDI pode dar suporte a até n codecs com endereços que variam de 0 a n-1.

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

[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

AllocateCaptureDmaEngine retornará STATUS_SUCCESS se a chamada for bem-sucedida na reserva de um mecanismo de DMA. Caso contrário, os possíveis valores retornados incluem os códigos de erro na tabela a seguir.

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 captura 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 AllocateCaptureDmaEngine 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 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 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 AllocateCaptureDmaEngine, o formato do fluxo pode ser alterado chamando ChangeBandwidthAllocation.

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 entrada. 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 AllocateCaptureDmaEngine, 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 (Modelo de Driver do Windows) chama AllocateCaptureDmaEngine no momento da criação do pin durante a execução de seu método NewStream (por exemplo, consulte IMiniportWavePci::NewStream).