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

Artigo
02/29/2024

A AllocateDmaBuffer rotina aloca um buffer de dados na memória do sistema para um mecanismo de DMA.

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

Sintaxe

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
)
{...}

Parâmetros

[in] _context

Especifica o valor de contexto dos membros Context das estruturas HDAUDIO_BUS_INTERFACE e HDAUDIO_BUS_INTERFACE_V2 .

[in] Handle

Manipule a identificação do mecanismo de AMD. Esse valor de identificador foi obtido de uma chamada anterior para AllocateCaptureDmaEngine ou AllocateRenderDmaEngine.

[in] RequestedBufferSize

Especifica o tamanho do buffer solicitado em bytes.

[out] BufferMdl

Recupera as páginas de memória física que contém o buffer alocado. Esse parâmetro aponta para uma variável PMDL alocada pelo chamador na qual a rotina grava um ponteiro em uma MDL (lista de descritores de memória) que descreve o buffer.

[out] AllocatedBufferSize

Recupera o tamanho do buffer alocado em bytes. Esse parâmetro aponta para uma variável de SIZE_T alocada pelo chamador na qual a rotina grava o tamanho do buffer alocado.

[out] StreamId

Recupera o identificador de fluxo. Esse parâmetro aponta para uma variável UCHAR alocada pelo chamador na qual a rotina grava o identificador de fluxo que ele atribui ao fluxo.

[out] FifoSize

Recupera o tamanho fifo do mecanismo de DMA em bytes. Esse parâmetro aponta para uma variável ULONG alocada pelo chamador na qual a rotina grava o tamanho do FIFO.

Retornar valor

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

Código de retorno	Descrição
STATUS_UNSUCCESSFUL	Indica que o chamador está em execução em um IRQL muito alto.
STATUS_INSUFFICIENT_RESOURCES	Indica que a alocação de buffer falhou.
STATUS_INVALID_HANDLE	Indica que o valor do parâmetro handle é inválido.
STATUS_INVALID_PARAMETER	Indica que um dos valores de parâmetro está incorreto (ponteiro inválido).
STATUS_DEVICE_NOT_READY	Indica que a programação de hardware atingiu o tempo limite. Se isso ocorrer, o hardware poderá estar em um estado comprometido.
STATUS_INVALID_DEVICE_REQUEST	Indica que o fluxo não está no estado de redefinição ou que um buffer já está alocado para o mecanismo de DMA.

Comentários

A AllocateDmaBuffer rotina é usada em conjunto com a rotina FreeDmaBuffer . Essas duas rotinas estão disponíveis apenas no HDAUDIO_BUS_INTERFACE e nas versões HDAUDIO_BUS_INTERFACE_V2 da DDI de áudio HD. Essa DDI não inclui as rotinas AllocateContiguousDmaBuffer, SetupDmaEngineWithBdl e FreeContiguousDmaBuffer , que nunca são usadas em conjunto com AllocateDmaBuffer e FreeDmaBuffer. Ao contrário de SetupDmaEngineWithBdl, que configura o mecanismo de DMA para usar um buffer de DMA alocado anteriormente, AllocateDmaBuffer aloca um buffer DMA e configura o mecanismo de DMA para usar o buffer.

Se o mecanismo DMA não puder usar um buffer do tamanho solicitado no parâmetro requestedBufferSize, a rotina alocará um buffer o mais próximo possível do tamanho solicitado.

O driver de função de um codec de áudio ou modem é responsável por programar o codec para gerenciar as transferências de dados e reconhecer o identificador de fluxo.

A rotina gera um MDL que lista as páginas de memória física que contêm o buffer. O endereço base do buffer coincide com o início da primeira página física na lista.

Durante o tempo de vida de um identificador de mecanismo de DMA, AllocateDmaBuffer pode ser chamado sucessivamente para alocar novos buffers de DMA. No entanto, antes de chamar AllocateDmaBuffer, qualquer buffer de DMA alocado anteriormente deve primeiro ser liberado chamando FreeDmaBuffer.

Durante as chamadas para AllocateDmaBuffer e FreeDmaBuffer, o mecanismo de DMA deve estar no estado de fluxo de redefinição. O mecanismo DMA está no estado de redefinição imediatamente após a chamada para AlocarXxxDmaEngine. Para alterar o mecanismo DMA para o estado de execução, chame SetDmaEngineState.

O tamanho do FIFO é o número máximo de bytes que o mecanismo de DMA pode conter em seu buffer interno. Dependendo da implementação de hardware, o tamanho FIFO de um mecanismo de DMA pode ser estático ou variar dinamicamente com alterações no formato de fluxo. Para obter mais informações sobre o tamanho do FIFO, consulte a Especificação de áudio de alta definição da Intel no site do Intel HD Audio .

Essa rotina falha e retorna o código de erro STATUS_INVALID_DEVICE_REQUEST em qualquer uma das seguintes circunstâncias:

Nenhum buffer de AMD alocado anteriormente não foi liberado (chamando FreeDmaBuffer).
O fluxo está em um estado diferente de redefinir.

No Windows Server 2003, Windows XP, Windows 2000 e Windows Me/98, um driver de áudio WDM chama essa rotina durante a execução de seu método NewStream (no momento da criação do pin) ou do método SetFormat (depois de chamar uma das rotinas AllocateXxxDmaEngine na DDI de áudio HD). Para obter mais informações, consulte IMiniportWavePci::NewStream e IMiniportWavePciStream::SetFormat.