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

Artigo
02/07/2025

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

O tipo de ponteiro de função para uma rotina de AllocateDmaBuffer é 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 de contexto das estruturas HDAUDIO_BUS_INTERFACE e HDAUDIO_BUS_INTERFACE_V2.

[in] Handle

Manipule a identificação do mecanismo de DMA. 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 por 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 por chamador na qual a rotina grava o identificador de fluxo que ele atribui ao fluxo.

[out] FifoSize

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

Valor de retorno

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 que é muito alto.
STATUS_INSUFFICIENT_RESOURCES	Indica que a alocação de buffer falhou.
STATUS_INVALID_HANDLE	Indica que o valor do parâmetro de identificador é inválido.
STATUS_INVALID_PARAMETER	Indica que um dos valores de parâmetro está incorreto (ponteiro incorreto).
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.

Observações

A rotina de AllocateDmaBuffer é usada em conjunto com a rotina de 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, SetupDmaEngineWithBdle FreeContiguousDmaBuffer, que nunca são usadas em conjunto com AllocateDmaBuffer e FreeDmaBuffer. Ao contrário de SetupDmaEngineWithBdl, que configura o mecanismo DMA para usar um buffer DMA alocado anteriormente, AllocateDmaBuffer aloca um buffer DMA e configura o mecanismo DMA para usar o buffer.

Se o mecanismo de 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 da 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 DMA deve estar no estado do 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 FIFO é o número máximo de bytes que o mecanismo DMA pode conter em seu buffer interno. Dependendo da implementação de hardware, o tamanho FIFO de um mecanismo 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 de áudio Intel HD.

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

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

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 método SetFormat (depois de chamar uma das rotinas de alocaçãoXxxDmaEngine no DDI de áudio HD). Para obter mais informações, consulte IMiniportWavePci::NewStream e IMiniportWavePciStream::SetFormat.