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

Artigo
07/27/2023

A rotina SetupDmaEngineWithBdl configura um mecanismo de DMA para usar um buffer de DMA alocado pelo chamador.

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

Sintaxe

PSETUP_DMA_ENGINE_WITH_BDL PsetupDmaEngineWithBdl;

NTSTATUS PsetupDmaEngineWithBdl(
  [in]  PVOID _context,
  [in]  HANDLE Handle,
  [in]  ULONG BufferLength,
  [in]  ULONG Lvi,
  [in]  PHDAUDIO_BDL_ISR Isr,
  [in]  PVOID Context,
  [out] PUCHAR StreamId,
  [out] PULONG FifoSize
)
{...}

Parâmetros

[in] _context

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

[in] Handle

Identificador que identifica o mecanismo de DMA. Esse valor de identificador foi obtido de uma chamada anterior para AllocateCaptureDmaEngine ou AllocateRenderDmaEngine.

[in] BufferLength

A duração do buffer.

[in] Lvi

Especifica o último LVI (índice válido). Esse parâmetro contém o índice do último descritor de buffer válido no BDL. Depois que o mecanismo de DMA processa esse descritor, ele é encapsulado novamente para o primeiro descritor na lista e continua o processamento. Se o BDL contiver n descritores, eles serão numerados de 0 a n-1. O valor lvi deve ser pelo menos 1; em outras palavras, o BDL deve conter pelo menos duas entradas válidas antes que o mecanismo de DMA possa iniciar a operação.

[in] Isr

Ponteiro de função para o ISR do chamador. Se o chamador definir o bit ioc (interrupção após a conclusão) em um ou mais descritores de buffer no BDL, o motorista do barramento de áudio HD chamará o ISR sempre que ocorrer uma interrupção do IOC no fluxo. Esse parâmetro é um ponteiro de função do tipo HDAUDIO_BDL_ISR, que é definido na seção Comentários a seguir.

[in] Context

O contexto.

[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 UINT alocada pelo chamador na qual a rotina grava o tamanho do FIFO.

Retornar valor

SetupDmaEngineWithBdl 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_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 ou formato de fluxo 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 dispositivo DMA ou o buffer de DMA não está alocado ou que o fluxo não está no estado Redefinir.

Comentários

A rotina SetupDmaEngineWithBdl é usada em conjunto com as rotinas AllocateContiguousDmaBuffer 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 de DMA e configura o mecanismo de DMA para usar o buffer.

O chamador deve chamar AllocateContiguousDmaBuffer para alocar armazenamento na memória do sistema para o buffer de DMA e o BDL que descreve as páginas de memória física no buffer. As entradas BDL devem residir na memória fisicamente contígua. O BDL e a memória de buffer devem atender aos requisitos de alinhamento descritos na Especificação de Áudio de Alta Definição da Intel (consulte o site do Áudio Intel HD ).

A BDL e a memória de buffer que ela descreve devem permanecer válidas durante as operações de DMA. Após a chamada para SetupDmaEngineWithBdl, a memória BDL e buffer devem permanecer válidas enquanto o mecanismo de DMA continuar a usar o buffer. O mecanismo DMA usa o buffer até que o driver de função substitua o buffer chamando SetupDmaEngineWithBdl novamente ou libere o mecanismo de DMA chamando FreeDmaEngine. O driver de função é responsável por chamar FreeContiguousDmaBuffer para liberar o buffer e o BDL quando eles não forem mais necessários.

Ao alocar memória para o buffer, o chamador deve atender a todas as restrições de hardware para o endereço, o comprimento e o alinhamento dos blocos fisicamente contíguos de memória especificados pelo BDL. Portanto, somente clientes com conhecimento significativo do controlador de barramento e do hardware do sistema devem usar a rotina SetupDmaEngineWithBdl .

Antes de chamar SetupDmaEngineWithBdl para configurar um mecanismo de DMA, o cliente deve chamar AllocateCaptureDmaEngine ou AllocateRenderDmaEngine para alocar o mecanismo de DMA. O parâmetro handle é o valor obtido da chamada anterior para Allocate XxxDmaEngine.

O chamador é responsável por programar o codec para gerenciar as transferências de dados e reconhecer o identificador de fluxo.

Um driver de áudio WDM chama essa rotina no momento da criação do pin durante a execução de seu método NewStream (por exemplo, consulte IMiniportWavePci::NewStream).

Após a chamada para SetupDmaEngineWithBdl, o mecanismo de DMA está no estado Redefinir. Para iniciar o mecanismo de DMA, chame SetDmaEngineState.

O isr de parâmetro especifica o ISR que o driver de barramento de áudio HD deve chamar sempre que ocorrer uma interrupção do IOC no fluxo. Esse parâmetro é um ponteiro de função do tipo HDAUDIO_BDL_ISR, que é definido como:

typedef void
  (*PHDAUDIO_BDL_ISR)
    (IN VOID *Context, IN ULONG InterruptBitMask);

O driver de barramento de áudio HD chama o ISR com o mesmo valor de contexto especificado pelo cliente no parâmetro de contexto da chamada setupDmaEngineWithBdl anterior. O parâmetro interruptBitMask contém os bits do fluxo do dispositivo do controlador de áudio HD status registro que indicam o motivo da interrupção. A tabela a seguir mostra o significado dos bits individuais em interruptBitMask.

Números de bits	Significado
31:5	Não utilizado.
4	Descriptor Error (DESE). Se ocorrer um erro durante a busca de um descritor de buffer, o controlador de áudio HD definirá o bit DESE como 1.
3	FIFO Error (FIFOE). Se ocorrer um erro FIFO (um estouro em um fluxo de saída ou um subexecutado em um fluxo de entrada), o controlador de áudio HD definirá o bit FIFOE como 1.
2	BCIS (Status de Interrupção de Conclusão do Buffer). Se o bit IOC for definido como 1 no byte de comando do descritor de buffer, o controlador de áudio HD definirá o bit BCIS como 1 depois que o último exemplo de um buffer for processado.
1:0	Não utilizado.

O driver do barramento de áudio HD define os bits não utilizados como zero. Em vez de assumir que ocorreu uma interrupção do COI, o ISR deve sempre marcar o parâmetro interruptBitMask para determinar se ocorreu um erro de fluxo. Para obter mais informações sobre a interrupção status bits mostrados na tabela anterior, consulte a descrição do fluxo status registros na Especificação de Áudio de Alta Definição da Intel.

O tamanho do FIFO é o número máximo de bytes que o mecanismo de DMA pode manter em seu buffer interno a qualquer momento. 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.

O chamador deve alocar a memória do buffer e o BDL do pool nãopagado.