EVT_ACX_STREAM_PREPARE_HARDWARE função de retorno de chamada (acxstreams.h)

Artigo
02/06/2025

O evento EvtAcxStreamPrepareHardware informa ao driver para preparar o hardware para streaming.

Sintaxe

EVT_ACX_STREAM_PREPARE_HARDWARE EvtAcxStreamPrepareHardware;

NTSTATUS EvtAcxStreamPrepareHardware(
  ACXSTREAM Stream
)
{...}

Parâmetros

Stream

Um objeto ACXSTREAM representa um fluxo de áudio criado por um circuito. O fluxo é composto por uma lista de elementos criados com base nos elementos do circuito pai. Para obter mais informações, consulte ACX – Resumo dos objetos ACX.

Valor de retorno

Retorna STATUS_SUCCESS se a chamada foi bem-sucedida. Caso contrário, ele retornará um código de erro apropriado. Para obter mais informações, consulte Usando valores NTSTATUS.

Observações

Um AcxStream dá suporte a estados diferentes. Esses estados indicam quando o áudio está fluindo (estado RUN), o áudio não está fluindo, mas o hardware de áudio está preparado (estado PAUSE) ou o áudio não está fluindo e o hardware de áudio não está preparado (estado STOP).

O evento EvtAcxStreamPrepareHardware fará a transição do estado do fluxo do estado Stop para o estado Pause. O driver deve alocar todos os recursos de hardware necessários para streaming nesse evento, como mecanismos de DMA.

Depois que o fluxo estiver no estado Pausar, o driver poderá receber o evento EvtAcxStreamRun para fazer a transição para o estado Executar ou o driver poderá receber o evento EvtAcxStreamReleaseHardware para fazer a transição para o estado Parar.

Os Eventos ACX são análogos aos estados KS, conforme descrito nesta tabela.

Estado de início	Estado final	Evento de driver ACX chamado	Anotações
PARAR	ADQUIRIR	PrepareHardware	O driver executa alocações e preparações de hardware
ADQUIRIR	PAUSA	(Sem chamada)
PAUSA	CORRER	Correr
CORRER	PAUSA	Pausa
PAUSA	ADQUIRIR	(Sem chamada)
ADQUIRIR	PARAR	ReleaseHardware	O driver libera alocações de hardware

EvtAcxStreamAllocateRtPackets é chamado antes de EvtAcxStreamPrepareHardware para permitir que a alocação de pacote RT ocorra antes de EvtAcxStreamPrepareHardware.

Alocações de buffer e DMA

Normalmente, a alocação de buffer envolve apenas a alocação de memória do sistema de forma que possa ser usada com o hardware de DMA. Normalmente, a alocação de buffer não terá nenhum efeito no hardware de streaming. A fase de hardware de preparação é usada porque o driver está preparando o fluxo para execução, concluindo tarefas como reservar largura de banda, programar DMA e concluir a preparação para a solicitação para executar o fluxo. Normalmente, o código de hardware de preparação usará os buffers alocados para preparar o DMA e atividades relacionadas para estar pronto para iniciar o fluxo.

Limpeza de memória

As alocações de pacote (memória física no sistema) são feitas antes do EvtAcxStreamPrepareHardware e sua versão (EvtAcxStreamFreeRtPackets) é feita após EvtAcxStreamReleaseHardware. Esse padrão é um comportamento herdado existente que é inserido no fluxo de configuração do fluxo de fluxo de áudio das camadas superiores (ks alocam o buffer prop init).

O descarte dos recursos do fluxo pode ser feito na limpeza de contexto do fluxo do driver (não destruir). Nunca coloque o descarte de nada que seja compartilhado no contexto de um objeto destruir o retorno de chamada. Essa orientação se aplica a todos os objetos ACX.

O retorno de chamada de destruição é invocado depois que o último ref se foi, quando é desconhecido.

O retorno de chamada de limpeza do fluxo é chamado quando o identificador é fechado. Uma exceção a isso é quando o driver criou o fluxo em seu retorno de chamada. Se o ACX não tiver adicionado esse fluxo à ponte de fluxo pouco antes de retornar da operação de criação de fluxo, o fluxo será cancelado como assíncrono e o thread atual retornará um erro para o cliente create-stream. O fluxo não deve ter alocações de mem alocadas neste momento.

Exemplo

O uso de exemplo é mostrado abaixo.

    ACX_STREAM_CALLBACKS streamCallbacks;
    ACX_STREAM_CALLBACKS_INIT(&streamCallbacks);
    streamCallbacks.EvtAcxStreamPrepareHardware     = Codec_EvtStreamPrepareHardware;
    ...
    status = AcxStreamInitAssignAcxStreamCallbacks(StreamInit, &streamCallbacks);

#pragma code_seg("PAGE")
NTSTATUS
Codec_EvtStreamPrepareHardware(
    _In_ ACXSTREAM Stream
    )
{
    PSTREAM_CONTEXT ctx;
    NTSTATUS        status;

    PAGED_CODE();

    ctx = GetStreamContext(Stream);

    status = AllocateStreamHardware(Stream);

    if (NT_SUCCESS(status))
    {
        ctx->StreamState = AcxStreamStatePause;
    }

    return status;
}

Requisitos do ACX

versão mínima do ACX: 1.0

Para obter mais informações sobre versões do ACX, consulte visão geral da versão do ACX.

Requisitos

Requisito	Valor
cabeçalho	acxstreams.h
IRQL	PASSIVE_LEVEL

Partilhar via