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

Artigo
08/07/2023

A AllocateContiguousDmaBuffer rotina aloca um buffer de AMD que consiste em um único bloco contíguo de memória física.

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

Sintaxe

PALLOCATE_CONTIGUOUS_DMA_BUFFER PallocateContiguousDmaBuffer;

NTSTATUS PallocateContiguousDmaBuffer(
  [in]  PVOID _context,
  [in]  HANDLE Handle,
        ULONG RequestedBufferSize,
  [out] PVOID *DataBuffer,
  [out] PHDAUDIO_BUFFER_DESCRIPTOR *BdlBuffer
)
{...}

Parâmetros

[in] _context

Especifica o valor de contexto do membro Context da estrutura HDAUDIO_BUS_INTERFACE_BDL .

[in] Handle

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

RequestedBufferSize

Especifica o tamanho do buffer solicitado em bytes.

[out] DataBuffer

Recupera o buffer de dados. Esse parâmetro aponta para uma variável PVOID alocada pelo chamador na qual a rotina grava o endereço virtual do sistema do buffer de dados.

[out] BdlBuffer

Recupera a BDL (lista de descritores de buffer). Esse parâmetro aponta para uma variável PVOID alocada pelo chamador na qual a rotina grava o endereço virtual do sistema do BDL. O tamanho da alocação de BDL é exatamente uma página de memória e o BDL começa em um limite de página.

Retornar valor

AllocateContiguousDmaBuffer 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 (nível de solicitação de interrupção) 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 AllocateContiguousDmaBuffer rotina é usada em conjunto com as rotinas SetupDmaEngineWithBdl e FreeContiguousDmaBuffer . Essas três rotinas estão disponíveis apenas na versão HDAUDIO_BUS_INTERFACE_BDL da DDI de áudio HD. Essa DDI não inclui as rotinas AllocateDmaBuffer e FreeDmaBuffer , que nunca são usadas em conjunto com AllocateContiguousDmaBuffer, SetupDmaEngineWithBdl e FreeContiguousDmaBuffer. 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. Para obter mais informações, consulte Diferenças entre as duas versões DDI.

AllocateContiguousDmaBuffer aloca um buffer de dados para o mecanismo de DMA especificado. Ele também aloca uma página de memória para o BDL. Dependendo da arquitetura do processador de host, um tamanho de página típico pode ser de 4.096 ou 8.192 bytes. O buffer de dados consiste em um único bloco contíguo de memória física.

O parâmetro handle especifica o mecanismo de DMA que deve usar o buffer de dados e o BDL. A rotina aloca armazenamento que atende aos requisitos de tamanho, alinhamento e posição do mecanismo de AMD.

O armazenamento alocado pela rotina para o buffer de dados e o BDL não é inicializado. O driver de função é responsável por preencher o BDL antes de enviá-lo para a rotina SetupDmaEngineWithBdl . O driver de função também é responsável por programar o codec para gerenciar as transferências de dados e reconhecer o identificador de fluxo.

Para gerar interrupções do IOC em intervalos precisos, o driver de função pode ser necessário para dividir a alocação do buffer de dados em vários fragmentos de um tamanho específico. Cada fragmento é descrito por uma entrada BDL. O tamanho do fragmento pode ser ajustado para ajustar a taxa de interrupção. De acordo com a Especificação de Áudio de Alta Definição da Intel (consulte o site do Intel HD Audio ), cada fragmento deve começar em um limite de 128 bytes, embora nenhum requisito de alinhamento se aplique ao comprimento do fragmento. Portanto, pode existir uma lacuna entre o final de um fragmento e o início do próximo. Ao chamar SetupDmaEngineWithBdl, o driver de função deve especificar um valor para o parâmetro bufferSize que representa a soma dos tamanhos dos fragmentos individuais descritos pelas entradas BDL. Esse tamanho será menor ou igual ao número de bytes especificado no AllocateContiguousDmaBuffer parâmetro requestedBufferSize da rotina.

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

Durante as chamadas para AllocateContiguousDmaBuffer, SetupDmaEngineWithBdl e FreeContiguousDmaBuffer, 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.

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