Gerenciamento da vida útil do driver WDF ACX

Artigo
05/27/2024

Este tópico fornece um resumo do gerenciamento do tempo de vida do driver WDF do ACX e da limpeza de memória adequada. Para obter uma visão geral do ACX, consulte Visão geral das extensões de classe de áudio ACX.

Observação

Os cabeçalhos e bibliotecas ACX não estão incluídos no WDK 10.0.22621.2428 (lançado em 24 de outubro de 2023), mas estão disponíveis em versões anteriores, bem como no Insider Preview mais recente (compilações da série 25000) do WDK. Para obter mais informações sobre versões prévias do WDK, consulte Instalar versões prévias do WDK (Kit de Driver do Windows).

Inicialização e ativação do ACX WDF

A inicialização adequada do ACX precisa ocorrer para permitir a limpeza adequada dos recursos de ACX, WDF e memória. Veja mais detalhes em Enumeração de dispositivo ACX sobre as principais fases da enumeração de dispositivo resumidas aqui.

Entrada de driver do WDM
Adicionar dispositivo WDF
Preparar o hardware WDF
Entrada dispositivo D0 do WDF
Processo de Criação de Circuito ACX (objetos Pinos e Conectores ACX estão associados ao Circuito)
Processo de Criação do Fluxo ACX

Limpeza de objeto WDF do ACX

Este tópico descreve a limpeza de objetos WDF do ACX nesta ordem.

Processo de fechamento de fluxo do ACX
Processo de remoção do circuito ACX
Hardware de lançamento de dispositivo WDF
Descarregamento do driver WDF

Há várias abordagens válidas para criar e limpar objetos WDF e ACX, mas este tópico aborda alguns elementos-chave do gerenciamento do tempo de vida de objetos ACX/WDF.

Eventos de energia PnP e destruição de objetos

Eventos de energia PnP podem causar a criação e destruição de objetos. Para obter mais informações sobre eventos de energia PnP, consulte Gerenciamento de energia ACX e Sequências de retorno de chamada de gerenciamento de energia e PnP do WDF.

Gerenciamento do tempo de vida de referência de objeto WDF

O WDF usa contagens de referência para ajudar a controlar o tempo de vida dos objetos. Pode ser apropriado em uma função de retorno de chamada de limpeza, para desreferenciar referências de objeto. A estrutura chama essa função de retorno de chamada de limpeza para que o driver possa solicitar WdfObjectDereference caso tenha chamado WdfObjectReference anteriormente para o objeto que está sendo excluído. Para obter mais informações, consulte WdfObjectReference e WdfObjectDereference.

Práticas recomendadas de desenvolvimento de drivers do Surface Team

Para obter uma descrição dos erros comuns cometidos no código do driver com o gerenciamento da memória e do tempo de vida do objeto, consulte essas seções em Práticas recomendadas de desenvolvimento de drivers do Surface Team.

Processo de fechamento de fluxo do ACX

Quando o cliente fecha o fluxo, o driver precisa trabalhar para fechar e limpar os recursos que estavam associados ao fluxo. Para obter mais detalhes, consulte Streaming ACX – Processo de fechamento de fluxo. É importante que o driver não limpe os recursos que suportam o fluxo e que o processo de limpeza considere os impactos no cliente.

Processo de remoção do circuito ACX

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 invoca AcxDeviceRemoveCircuitDevice para remover o dispositivo de áudio da lista de dispositivos.

Para obter mais informações, consulte Remoção dinâmica de circuito ACX em circuitos ACX.

Hardware de lançamento de dispositivo WDF

A função de retorno de chamada EVT_WDF_DEVICE_RELEASE_HARDWARE é usada na função de retorno de chamada de evento EvtDeviceReleaseHardware de um driver para executar operações necessárias quando um dispositivo não está mais acessível.

Limpeza de contexto do dispositivo WDF

Este código do exemplo AudioCodec mostra o uso de uma estrutura WDF_OBJECT_ATTRIBUTES para definir um EvtCleanupCallback.

    WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&attributes, CODEC_DEVICE_CONTEXT);
    attributes.EvtCleanupCallback = Codec_EvtDeviceContextCleanup;

Este retorno de chamada de exemplo WdfDevice limpa o contexto do dispositivo.

VOID
Codec_EvtDeviceContextCleanup(
    _In_ WDFOBJECT      WdfDevice
)

{
    WDFDEVICE               device;
    PCODEC_DEVICE_CONTEXT   devCtx;

    device = (WDFDEVICE)WdfDevice;
    devCtx = GetCodecDeviceContext(device);
    ASSERT(devCtx != nullptr);

    if (devCtx->Capture)
    {
        CodecC_CircuitCleanup(devCtx->Capture);
    }
}

Descarregamento do driver WDF

Quando o driver é descarregado, ele liberará todos os recursos restantes. Para obter mais informações, consulte Liberar recursos alocados pelo driver.

Um driver registra uma função de retorno de chamada EvtDriverUnload quando chama WdfDriverCreate. A função de retorno de chamada EvtDriverUnload deve desalocar quaisquer recursos do sistema não específicos ao dispositivo que a rotina DriverEntry do driver alocou. Para obter mais informações, consulte a função de retorno de chamada EVT_WDF_DRIVER_UNLOAD.

Este código do exemplo AudioCodec mostra a estrutura de um retorno de chamada de descarregamento de driver.

EVT_WDF_DRIVER_UNLOAD               AudioCodecDriverUnload;

void AudioCodecDriverUnload(
    _In_ WDFDRIVER Driver
)
{
    PAGED_CODE();

    if (!Driver)
    {
        ASSERT(FALSE);
        return;
    }

    WPP_CLEANUP(WdfDriverWdmGetDriverObject(Driver));

// Here is where you would cleanup any allocated resources associated with the driver.

    return;
}