Registro em log e depuração de ACX

Artigo
06/19/2024

Este tópico fornece informações sobre log, rastreamento e depuração das extensões de classe de áudio (ACX).

Log de driver do ACX

O rastreamento de software para drivers geralmente é baseado no rastreamento de eventos para Windows (ETW), um recurso no nível do kernel que registra mensagens de rastreamento para processos no modo kernel e no modo de usuário. Como os drivers do ACX são drivers do WDF, todos os recursos de log e eventos do WDF estão disponíveis para desenvolvedores de drivers do ACX.

WPP

Como o ETW pode ser um pouco complicado de usar, a maioria dos desenvolvedores de drivers usa o WPP (pré-processador de rastreamento de software) do Windows, que simplifica e aprimora o processo de instrumentação de um driver para rastreamento ETW.

O ACX usa logs do WPP para rastreamento e depuração. Para obter mais informações, consulte Usar o rastreamento de software do WPP em drivers da KMDF e Adicionar rastreamento de software do WPP a um driver do Windows.

Gravador em andamento (IFR)

O gravador em andamento (IFR) é suportado e pode ser visualizado via WDFKD, RCDRKD ou com a extensão do depurador de ACXKD quando disponível. Para obter informações gerais sobre como trabalhar com logs de IFR, consulte Usar o gravador de rastreamento em andamento (IFR) em drivers da KMDF e UMDF 2 e Vídeo: acessar logs de IFR de driver sem um depurador

O ACX registra eventos-chave usando outros provedores de ETW para simplificar a visualização desses eventos especiais.

Adicionar registro em log ao seu driver

Os drivers de terceiros são altamente encorajados a usar eventos WPP e ETW também.

Esse código de exemplo mostra a verificação de um valor de retorno e o registro de um erro apropriado.


    //
    // The driver uses this DDI to delete the circuits from the current device. 
    //
    status = AcxDeviceRemoveCircuit(Device, devCtx->Speaker);
    if (!NT_SUCCESS(status)) { DrvLogError(g_AudioDspLog, FLAG_INIT, L"Failed to remove speaker circuit, continuing with ReleaseHardware, %!STATUS!", status); }
    status = AcxDeviceRemoveCircuit(Device, devCtx->MicArray);
    if (!NT_SUCCESS(status)) { DrvLogError(g_AudioDspLog, FLAG_INIT, L"Failed to remove micarray circuit, continuing with ReleaseHardware, %!STATUS!", status); }
    status = AcxDeviceRemoveCircuit(Device, devCtx->SpeakerHp);
    if (!NT_SUCCESS(status)) { DrvLogError(g_AudioDspLog, FLAG_INIT, L"Failed to remove speakerHp circuit, continuing with ReleaseHardware, %!STATUS!", status); }
    status = AcxDeviceRemoveCircuit(Device, devCtx->MicrophoneHp);
    if (!NT_SUCCESS(status)) { DrvLogError(g_AudioDspLog, FLAG_INIT, L"Failed to remove microphoneHp circuit, continuing with ReleaseHardware, %!STATUS!", status); }
    status = AcxDeviceRemoveCircuit(Device, devCtx->HDMI);
    if (!NT_SUCCESS(status)) { DrvLogError(g_AudioDspLog, FLAG_INIT, L"Failed to remove HDMI circuit, continuing with ReleaseHardware, %!STATUS!", status); }

A versão em destaque do código de exemplo do driver Toaster fornece exemplos de rastreamento de WMI, bem como código de rastreamento reutilizável. Para obter mais informações sobre o exemplo do Toaster, consulte Driver de exemplo do Toaster.

Recomendações para registro em log do driver do ACX

Para melhorar a confiabilidade do driver do ACX, considere os seguintes comportamentos para registro em log.

Valores de retorno inesperados de E/S do buffer de fluxo ou outra atividade regular de processamento de sinal.
Estados de energia inesperados ou transições de estado de energia.
Erros relacionados a chamadas feitas durante atualizações ou reinstalação.
Outros comportamentos que podem levar a "nenhum áudio" podem ser considerados para registro em log.

Usar as extensões do depurador de rastreamento do WMI

Para exibir eventos de rastreamento no depurador, use a extensão WMI, Wmitrace.dll. Ele contém uma biblioteca de funções projetadas para controlar e exibir o rastreamento de eventos do WMI. Para obter mais informações, consulte Extensões de rastreamento de WMI (Wmitrace.dll).

Depuração de driver do ACX

Os drivers do ACX são drivers do WDF, portanto, as técnicas de depuração descritas para drivers do WDF se aplicam aos drivers do ACX. Consulte os tópicos a seguir para obter informações sobre como depurar drivers do WDF.

Informações gerais sobre as ferramentas de depuração

Ferramentas de depuração para Windows (WinDbg, KD, CDB, NTSD)

Depuração do KMDF

Resumo das extensões do depurador no Wdfkd.dll
Este passo a passo usa o driver de áudio Sysvad tradicional, mas ilustra algumas técnicas que podem ser úteis para drivers do ACX. Depurar drivers: laboratório passo a passo (modo kernel Sysvad)

Orientações em vídeo

Biblioteca de extensão do depurador do kernel do ACX (AcxKd.dll)

Para ajudar na depuração, o ACX tem uma biblioteca de extensão do depurador de kernel complementar (AcxKd.dll). Essa biblioteca ajuda os desenvolvedores a rastrear problemas em caminhos de áudio de pilha única e múltipla. A extensão kd permite que o desenvolvedor olhe dentro das estruturas do ACX.

Observação

Essa extensão do depurador está em desenvolvimento, e as informações serão fornecidas aqui quando estiverem disponíveis.

Confira também

Visão geral de extensões de classe de áudio ACX

Resumo de objetos ACX

Compartilhar via