Função KeSetHardwareCounterConfiguration (ntddk.h)

A rotina KeSetHardwareCounterConfiguration especifica uma lista de contadores de hardware a serem usados para criação de perfil de thread.

Sintaxe

NTSTATUS KeSetHardwareCounterConfiguration(
  [in] PHARDWARE_COUNTER CounterArray,
  [in] ULONG             Count
);

Parâmetros

[in] CounterArray

Um ponteiro para uma matriz HARDWARE_COUNTER que descreve a configuração do contador de hardware a ser usada para criação de perfil de thread. Cada elemento de matriz é uma estrutura que descreve um contador de hardware. Antes que a rotina retorne, ela copia o conteúdo dessa matriz em suas estruturas de dados internas.

[in] Count

Especifica o número de elementos na matriz apontada pelo parâmetro CounterArray .

Retornar valor

KeSetHardwareCounterConfiguration retornará STATUS_SUCCESS se a chamada for bem-sucedida. Os possíveis valores retornados por erro incluem o seguinte:

Código de retorno	Descrição
STATUS_INVALID_PARAMETER	O valor do parâmetro Count excede o número máximo de contadores especificados pela constante MAX_HW_COUNTERS, que é definida no arquivo de cabeçalho Ntddk.h.
STATUS_WMI_ALREADY_ENABLED	Um ou mais dos contadores especificados na matriz CounterArray já estão habilitados.
STATUS_NOT_IMPLEMENTED	Essa rotina não é implementada para a arquitetura do processador na qual o chamador está sendo executado.

Comentários

No Windows 7, essa rotina é implementada apenas para as arquiteturas baseadas em x86, baseadas em x64 e itanium. Se um chamador estiver em execução em uma arquitetura de processador sem suporte, a rotina retornará STATUS_NOT_IMPLEMENTED.

Essa rotina informa ao sistema operacional quais contadores de hardware usar para criação de perfil de thread. Chame essa rotina somente quando a criação de perfil de thread estiver desabilitada. Se a matriz CounterArray especificar os contadores de hardware que estão sendo usados no momento, a rotina falhará e retornará STATUS_WMI_ALREADY_ENABLED.

Um thread de aplicativo pode habilitar a criação de perfil de thread para obter um conjunto de medidas de desempenho dos contadores de hardware na PMU (unidade de monitoramento de desempenho) do processador local. O sistema operacional dá suporte a apenas um aplicativo de criação de perfil por vez. Não há suporte para instâncias simultâneas de um aplicativo de criação de perfil de thread. Um thread pode habilitar a criação de perfil de thread para si mesmo, mas não para outros threads.

Quando a criação de perfil de thread está habilitada, o sistema operacional usa os contadores de hardware que foram especificados na última chamada para KeSetHardwareCounterConfiguration. Cada chamada keSetHardwareCounterConfiguration bem-sucedida substitui qualquer configuração de contador de hardware que possa ter sido definida em uma chamada keSetHardwareCounterConfiguration anterior.

Defina Contagem = 0 para especificar uma configuração de contador de hardware vazia. Essa configuração impede efetivamente o uso de contadores de hardware para criação de perfil de thread. A configuração do contador de hardware padrão que existe após a inicialização do sistema e antes da chamada keSetHardwareCounterConfiguration inicial é uma configuração vazia.

O efeito de uma chamada KeSetHardwareCounterConfiguration bem-sucedida é global. Se um thread em qualquer processo for criado com perfil, o criador de perfil usará a configuração do contador de hardware que foi definida pela última chamada para KeSetHardwareCounterConfiguration. Em um sistema multiprocessador, uma chamada KeSetHardwareCounterConfiguration define a configuração do contador de hardware a ser usada para criação de perfil de thread em todos os processadores no sistema, embora cada processador use seu próprio conjunto de contadores de hardware.

Para evitar conflitos de recursos, todos os drivers que usam recursos de contador devem usar as rotinas HalAllocateHardwareCounters e HalFreeHardwareCounters para coordenar o compartilhamento desses recursos.

Para determinar se a criação de perfil de thread está habilitada para um determinado thread, chame a função QueryThreadProfiling .

Para consultar o sistema operacional para a configuração do contador de hardware que está atualmente em vigor para criação de perfil de thread, chame a rotina KeQueryHardwareCounterConfiguration .

O software de virtualização normalmente não virtualiza contadores de desempenho de hardware. Portanto, é improvável que os contadores de desempenho de hardware estejam disponíveis em uma máquina virtual.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível a partir do Windows 7.
Plataforma de Destino	Universal
Cabeçalho	ntddk.h (inclua Ntddk.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL

Confira também

Referência de criação de perfil de contador de hardware

HARDWARE_COUNTER

HalAllocateHardwareCounters

HalFreeHardwareCounters

KeQueryHardwareCounterConfiguration