Usando o IFR (Gravador de Rastreamento De Voo) em drivers KMDF e UMDF 2
Começando no Windows 10, você pode criar seu driver KMDF ou UMDF para que ele obtenha informações extras de depuração de driver por meio do pré-processamento de rastreamento de software do Windows. Esse recurso, chamado IFR (Inflight Trace Recorder), está disponível a partir do KMDF versão 1.15 e UMDF versão 2.15.
O Inflight Trace Recorder é uma extensão do rastreamento de software WPP. Ao contrário do rastreamento do WPP, o Inflight Trace Recorder continua funcionando sem um consumidor de rastreamento anexado. A estrutura grava mensagens em um buffer circular e o driver também pode adicionar suas próprias mensagens. Cada driver tem seu próprio log, portanto, vários dispositivos associados a um driver compartilham um único log.
Se você ativar o IFR no binário do driver, o IFR estará presente e em execução durante o tempo de vida do driver. Você não precisa iniciar uma sessão de coleta de rastreamento explícita.
Os logs são armazenados em memória não paginável, portanto, podem ser recuperados após uma falha do sistema. Além disso, os logs do Inflight Trace Recorder são incluídos em arquivos de minidespejo, exceto quando o driver responsável é indeterminado ou se a falha foi um tempo limite do host.
Como habilitar o Inflight Trace Recorder e enviar mensagens do driver
No Microsoft Visual Studio, execute as seguintes etapas:
Abra as Páginas de Propriedades do seu projeto de driver. Clique com o botão direito do mouse no projeto do driver no Gerenciador de Soluções e selecione Propriedades. Nas Páginas de Propriedades do driver, selecione Propriedades de Configuração e Rastreamento do Wpp. No menu Geral , defina Executar Rastreamento WPP como Sim.
Navegue até Propriedades-Wpp> Tracing-Function e Opções de> Macro e escolha Habilitar Gravador WPP.
No mesmo menu, defina Verificar Dados de Configuração como o arquivo que contém suas informações de rastreamento, por exemplo Trace.h.
Em cada arquivo de origem que chama uma macro WPP, adicione uma diretiva #include que identifica um arquivo TMH (cabeçalho de mensagem de rastreamento). O nome do arquivo deve ter um formato de <driver-source-file-name.tmh.>
Por exemplo, se o driver consistir em dois arquivos de origem, chamados MyDriver1.c e MyDriver2.c, MyDriver1.c deverá conter:
#include "MyDriver1.tmh"
e MyDriver2.c devem conter:
#include "MyDriver2.tmh"
Quando você cria o driver no Visual Studio, o pré-processador WPP gera o . arquivos tmh .
Defina uma macro WPP_CONTROL_GUIDS em um arquivo de cabeçalho. Essa macro define um GUID e sinalizadores de rastreamento para as mensagens de rastreamento do driver.
O exemplo de driver Osrusbfx2 define um ÚNICO GUID de controle e sete sinalizadores de rastreamento no arquivo de cabeçalho Trace.h, conforme mostrado no exemplo a seguir:
#define WPP_CONTROL_GUIDS \ WPP_DEFINE_CONTROL_GUID(OsrUsbFxTraceGuid, \ (d23a0c5a,d307,4f0e,ae8e,E2A355AD5DAB), \ WPP_DEFINE_BIT(DBG_INIT) /* bit 0 = 0x00000001 */ \ WPP_DEFINE_BIT(DBG_PNP) /* bit 1 = 0x00000002 */ \ WPP_DEFINE_BIT(DBG_POWER) /* bit 2 = 0x00000004 */ \ WPP_DEFINE_BIT(DBG_WMI) /* bit 3 = 0x00000008 */ \ WPP_DEFINE_BIT(DBG_CREATE_CLOSE) /* bit 4 = 0x00000010 */ \ WPP_DEFINE_BIT(DBG_IOCTL) /* bit 5 = 0x00000020 */ \ WPP_DEFINE_BIT(DBG_WRITE) /* bit 6 = 0x00000040 */ \ WPP_DEFINE_BIT(DBG_READ) /* bit 7 = 0x00000080 */ \ )Neste exemplo:
- OsrUsbFxTraceGuid é o nome amigável do GUID {d23a0c5a-d307-4f0e-ae8e-E2A355AD5DAB}.
- Os sinalizadores de rastreamento são usados para diferenciar entre mensagens de rastreamento geradas à medida que o driver lida com diferentes tipos de solicitações de E/S.
Seu driver (KMDF e UMDF 2) deve chamar WPP_INIT_TRACING para drivers de Kernel-Mode com o objeto driver e um caminho do Registro, normalmente de DriverEntry:
WPP_INIT_TRACING( DriverObject, RegistryPath );Para desativar o rastreamento, os drivers KMDF e UMDF 2 chamam WPP_CLEANUP para drivers de Kernel-Mode de EvtCleanupCallback ou EvtDriverUnload:
WPP_CLEANUP( WdfDriverWdmGetDriverObject( Driver ));A macro WPP_CLEANUP usa um parâmetro do tipo PDRIVER_OBJECT, portanto, se o DriverEntry do driver falhar, você poderá ignorar a chamada de WdfDriverWdmGetDriverObject e, em vez disso , chamar WPP_CLEANUP com um ponteiro para o objeto de driver WDM.
Como os drivers UMDF usam as assinaturas do modo kernel dessas macros para inicializar e limpar o rastreamento, as chamadas parecem idênticas para KMDF e UMDF.
Use a macro DoTraceMessage ou uma versão personalizada da macro no driver para criar mensagens de rastreamento.
O exemplo a seguir mostra como o driver Osrusbfx2 usa sua função TraceEvents em uma parte do código dedicada ao tratamento de solicitações de leitura:
if (Length > TEST_BOARD_TRANSFER_BUFFER_SIZE) { TraceEvents(TRACE_LEVEL_ERROR, DBG_READ, "Transfer exceeds %d\n", TEST_BOARD_TRANSFER_BUFFER_SIZE); status = STATUS_INVALID_PARAMETER; }A chamada para TraceEvents gerará uma mensagem de rastreamento se o controlador de rastreamento habilitar o nível de TRACE_LEVEL_ERROR e o sinalizador de rastreamento DBG_READ . A mensagem inclui o valor da constante definida pelo driver TEST_BOARD_TRANSFER_BUFFER_SIZE.
Para alterar o tamanho do buffer circular que o log de driver usa, modifique o valor do registro LogPages no seguinte local do Registro:
SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\<YourDriver>\Parameters\Wdf
<HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\YourDriver>\Parameters\Wdf
Esse é um valor do tipo REG_DWORD que contém o tamanho do buffer de log alocado, em páginas. Os valores válidos estão entre 0x1 e 0x10.
Para um driver KMDF
- Carregue os comandos RCDRKD digitando .load rcdrkd.dll no depurador.
- Use a extensão !wdfkd.wdfldr para exibir informações sobre o driver que estão vinculados dinamicamente ao WDF (Windows Driver Frameworks).
- Use !rcdrkd.rcdrlogdump e !rcdrkd.rcdrcrashdump para exibir mensagens que o driver fornece.
- Use !wdfkd.wdflogdump ou !wdfkd.wdfcrashdump para ver as mensagens que a estrutura fornece.
Depuração dinâmica de um driver UMDF
Use a extensão !wdfkd.wdfldr para exibir informações sobre os drivers que estão vinculados dinamicamente ao WDF no momento. Localize seu driver de modo de usuário. Insira o processo de host associado.
Digite !wdfkd.wdflogdump<YourDriverName.dll><Sinalizador> , em que <Sinalizador> é:
- 0x1 – estrutura mesclada e logs de driver
- 0x2 – Logs de driver
- 0x3 – Logs de estrutura
Se não houver nenhum log de driver para o driver especificado, a extensão exibirá apenas o log da estrutura.
Exibindo logs do Gravador de Rastreamento de Bordo após uma falha de driver UMDF
No WinDbg, selecione Despejo de> Memória aberto por arquivo e especifique o arquivo de minidespejo que você deseja depurar.
Digite !wdfkd.wdfcrashdump <YourDriverName.dll><ID do processo da Opção> de host><do driver, em <que Option> é:
- 0x1 – estrutura mesclada e logs de driver
- 0x2 – Logs de driver
- 0x3 – Logs de estrutura
Se você não especificar um driver, !wdfcrashdump exibirá informações para todos os drivers. Se você não especificar um processo de host e houver apenas um, a extensão usará o processo de host único. Se você não especificar um processo de host e houver mais de um, a extensão listará os processos de host ativos.
Se as informações de log armazenadas no minidespejo não corresponderem ao nome inserido, o minidespejo não conterá os logs do driver.
Se você não tiver um depurador conectado, ainda poderá acessar os logs do driver e da estrutura. Para saber como, confira Vídeo: Acessando logs de IFR do driver sem um depurador.
Para obter mais informações sobre como adicionar mensagens de rastreamento ao driver, consulte Adicionando macros WPP a um driver.
Artigos relacionados
Como habilitar a depuração de um driver UMDF
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de