Circuitos ACX

Artigo
06/19/2024

Este tópico discute circuitos ACX. Para obter uma visão geral do ACX e uma lista de termos do ACX, consulte Visão geral das extensões de classe de áudio ACX.

Conforme descrito em Resumo de objetos ACX, um objeto AcxCircuit representa um caminho de áudio parcial ou total para um dispositivo de áudio percebido pelo usuário (alto-falantes, microfone etc.). Um AcxCircuit tem pelo menos um pino de entrada e um de saída (ACXPIN) e pode agregar um ou mais objetos do tipo AcxElements. O circuito representa um ponto de extremidade existente e suas capacidades.

E Transmissão do ACX é um componente de driver criado para representar uma transmissão de áudio, criada por um circuito. A transmissão é composta por uma lista de elementos criados com base nos elementos do circuito pai. Um circuito de transmissão é um circuito em uma arquitetura de pilha múltipla (caminho de áudio parcial) que faz interface direta com o serviço de streaming de modo de usuário superior. Um circuito principal é um circuito em uma arquitetura de pilha múltipla (caminho de áudio parcial) que fornece a identidade do dispositivo de ponto de extremidade de áudio.

Identificação do circuito do ACX

Cada circuito do ACX tem um identificador de circuito. O ACX define o seguinte:

Nome (str) identifica exclusivamente esse tipo de dispositivo de áudio de circuito. Ele é usado para localizar a configuração do INF e faz parte do link simbólico usado para acessar esse circuito de um dispositivo remoto. Exemplo: "Render0", "Render1" ou "Capture0".
Link simbólico. Um link simbólico está associado a todos os circuitos expostos. Os clientes usam esse link simbólico para abrir um caminho de comunicação com o dispositivo/circuito.
ID do componente do circuito (guid). Identifica exclusivamente a instância do circuito (específica do fornecedor). Ele não pode ser usado nas associações AcxCircuitTemplate se o URI do circuito tiver sido especificado.
URI do componente do circuito (str). Identifica exclusivamente a instância do circuito (específica do fornecedor). Ele não pode ser usado nas associações AcxCircuitTemplate se o ID do circuito tiver sido especificado.
ID do componente (guid) da fábrica de circuitos. Identifica exclusivamente a instância da fábrica do circuito (específica do fornecedor). Ele não pode ser usado nas associações AcxCircuitTemplate se o URI da fábrica do circuito tiver sido especificado.
URI do componente da fábrica do circuito (str). Identifica exclusivamente a instância da fábrica do circuito (específica do fornecedor). Ele não pode ser usado nas associações AcxCircuitTemplate se o ID da fábrica do circuito tiver sido especificado.

AcxCircuitCreate

A função AcxCircuitCreate é usada para criar um ACXCIRCUIT. Uma estrutura ACXCIRCUIT_INIT opaca que é usada pela função AcxCircuitCreate. AcxCircuitInitAllocate é usado para inicializar a estrutura ACXCIRCUIT_INIT.

AcxFactoryCircuit

Um driver do ACX também pode criar objetos AcxFactoryCircuit (provedores de circuito) durante a sequência de inicialização usando a função AcxFactoryCircuitCreate e a função AcxDeviceAddFactoryCircuit.

Composição de circuitos ACX

O ACX associa os circuitos até que eles formem um caminho de áudio completo. O ACX usa associações de áudio para conectar circuitos de áudio juntos. Para obter mais informações, consulte Composição de vários Circuitos ACX.

Criação dinâmica de circuitos ACX (a qualquer momento)

ACX pode criar um circuito dinâmico sob demanda. Para fazer isso, o driver aloca uma estrutura WDFDEVICE_INIT chamando WdfPdoInitAllocate. Em seguida, o driver especifica todos os retornos de chamada PnP/power que deseja receber e cria o dispositivo. O driver instancia o novo dispositivo/circuito chamando AcxDeviceAddCircuitDevice. Para obter mais informações, consulte Enumeração de dispositivo ACX.

Remoção dinâmica do circuito do ACX

O driver invoca AcxDeviceRemoveCircuitDevice para remover o dispositivo de áudio da lista de dispositivos. Isso aciona a sequência de desligamento no dispositivo/entidade de circuito do ACX. O dispositivo do circuito/circuito é excluído de forma assíncrona. Para obter mais informações, consulte Enumeração de dispositivo ACX.

AcxDeviceRemoveCircuit e AcxDeviceDetachCircuit

Há duas maneiras comuns de gerenciar a terminação do circuito. AcxDeviceDetachCircuit ou AcxDeviceRemoveCircuit.

Se o chamador invocar o AcxDeviceDetachCircuit, ele não deve chamar AcxDeviceRemoveCircuit. Se o driver de chamada quiser excluir o circuito após AcxDeviceDetachCircuit, ele deve usar WdfObjectDelete.

Ao chamar AcxDeviceRemoveCircuit, o driver de chamada diz ao ACX para remover esse circuito e removê-lo/excluí-lo do dispositivo. Nesse caso, não há necessidade de chamar WdfObjectDelete no circuito.

Em resumo, AcxDeviceDetachCircuit significa que o driver possui o gerenciamento da vida útil dos objetos do circuito, AcxDeviceRemoveCircuit significa que o circuito será removido e excluído.

Para obter informações gerais sobre o gerenciamento do tempo de vida útil do objeto WDF, consulte Ciclo de vida do objeto da estrutura.

AcxDeviceRemoveCircuitDevice

Diferente da terminação do circuito discutida acima, AcxDeviceRemoveCircuitDevice é usado pelo driver de áudio para remover um ponto de extremidade de áudio existente e pode ser chamado a qualquer momento durante o ciclo de vida do driver.

Os drivers também podem optar por sempre destruir e recriar dispositivos de áudio na redistribuição. Esse é o mesmo cenário acima, quando o dispositivo detecta que as novas configurações não são compatíveis com as antigas.

A exclusão do circuito deve ser feita em retornos de chamada EvtDevicePrepareHardware/EvtDeviceReleaseHardware, e o novo circuito é recriado em EvtDevicePrepareHardware. O driver exclui um circuito cancelando o registro do circuito (usando AcxDeviceRemoveCircuit).

Função de retorno de chamada EvtAcxCircuitReleaseHardware (EVT_ACX_CIRCUIT_RELEASE_HARDWARE)

Se um driver tiver registrado uma função de retorno de chamada EvtAcxCircuitReleaseHardware, a estrutura a chamará durante as seguintes transições:

Rebalanceamento de recursos
Remoção ordenada
Remoção surpresa

A estrutura do ACX chama a função de retorno de chamada EvtAcxCircuitReleaseHardware depois que a estrutura WDF para de enviar solicitações de E/S para o dispositivo, todas as interrupções atribuídas ao dispositivo são desativadas e desconectadas e o dispositivo é desativado.

A estrutura do ACX chama a função de retorno de chamada EvtAcxCircuitReleaseHardware antes que a estrutura WDF chame a função de retorno de chamada EvtDeviceReleaseHardware do driver.

Quando a estrutura chama o EvtAcxCircuitReleaseHardware, o PDO para o dispositivo ainda existe e pode ser consultado para obter informações do dispositivo que estão disponíveis no estado desligado, por exemplo, o estado de configuração de PCI.

Além disso, os recursos de hardware traduzidos que a estrutura fornece para EvtDeviceReleaseHardware ainda são atribuídos ao dispositivo. O objetivo principal dessa função de retorno de chamada é liberar esses recursos e, em particular, desmapear quaisquer recursos de memória mapeados pela função de retorno de chamada EvtAcxCircuitPrepareHardware do driver. O driver também pode usar esse retorno de chamada para executar qualquer outra atividade de gerenciamento de circuito do ACXCIRCUIT que possa ser necessária no estado desligado. Normalmente, todas as outras operações de desligamento de hardware devem ocorrer na função de retorno de chamada EvtDeviceD0Exit do driver.

A estrutura do ACX sempre chama a função de retorno de chamada EvtAcxCircuitReleaseHardware do driver se a função de retorno de chamada EvtAcxCircuitPrepareHardware do driver tiver sido chamada, a menos que o EvtAcxCircuitPrepareHardware tenha retornado um código de falha.

Para obter mais informações sobre recursos de hardware, consulte Introdução aos recursos de hardware.

Função de retorno de chamada EvtAcxFactoryCircuitReleaseHardware (EVT_ACX_FACTORY_CIRCUIT_RELEASE_HARDWARE)

Quando a estrutura chama o EvtAcxFactoryCircuitReleaseHardware, o PDO para o dispositivo ainda existe e pode ser consultado para obter informações do dispositivo que estão disponíveis no estado desligado, por exemplo, o estado de configuração de PCI.

A estrutura do ACX sempre chama a função de retorno de chamada EvtAcxFactoryCircuitReleaseHardware do driver se a função de retorno de chamada EvtAcxFactoryCircuitPrepareHardware do driver tiver sido chamada, a menos que o EvtAcxFactoryCircuitPrepareHardware tenha retornado um código de falha.

Para obter mais informações sobre como gerenciar objetos WDF e de circuito, consulte ACX WDF Driver Lifetime Management.