Função HalAllocateHardwareCounters (ntddk.h)

  • Artigo

A rotina HalAllocateHardwareCounters aloca um conjunto de recursos de contador de desempenho de hardware.

Sintaxe

NTHALAPI NTSTATUS HalAllocateHardwareCounters(
        PGROUP_AFFINITY                 GroupAffinty,
  [in]  ULONG                           GroupCount,
  [in]  PPHYSICAL_COUNTER_RESOURCE_LIST ResourceList,
  [out] PHANDLE                         CounterSetHandle
);

Parâmetros

GroupAffinty

Um ponteiro para um conjunto de estruturas GROUP_AFFINITY indicando quais recursos de contador de processadores o consumidor solicita. Se esse parâmetro for NULL, a solicitação indicará uma alocação em todos os processadores no sistema.

[in] GroupCount

Fornece o número de estruturas de GROUP_AFFINITY fornecidas pelo parâmetro GroupAffinty ou zero se GroupAffinity for NULL.

[in] ResourceList

Um ponteiro para um PHYSICAL_COUNTER_RESOURCE_LIST que contém os recursos exigidos pelo consumidor. Se esse parâmetro for NULL, o consumidor solicitará a propriedade exclusiva da unidade de monitoramento de desempenho.

[out] CounterSetHandle

Um ponteiro para um local no qual a rotina grava um identificador nos recursos de contador alocados. Para liberar esses recursos posteriormente, o chamador deve passar esse identificador para a rotina HalFreeHardwareCounters . Se os recursos de contador solicitados não estiverem disponíveis, HalAllocateHardwareCounters definirá *CounterSetHandle = NULL e retornará STATUS_INSUFFICIENT_RESOURCES.

Retornar valor

HalAllocateHardwareCounters retornará STATUS_SUCCESS se a chamada tiver sido bem-sucedida. Os possíveis valores retornados por erro incluem os seguintes códigos de status.

Código de retorno Descrição
STATUS_INSUFFICIENT_RESOURCES Os recursos de contador solicitados não estão disponíveis no momento.
STATUS_INVALID_PARAMETER O chamador especificou um valor de parâmetro inválido.
STATUS_NOT_SUPPORTED O chamador forneceu recursos na lista de recursos que atualmente não têm suporte.

Comentários

A maioria dos processadores tem PMUs (unidades de monitor de desempenho) que contêm vários contadores de hardware. As ferramentas de software usam esses contadores para monitorar vários aspectos do desempenho do sistema. Normalmente, essa ferramenta consiste em um driver de modo kernel personalizado para programar os contadores e um aplicativo de modo de usuário que se comunica com o driver.

Se mais de uma dessas ferramentas estiver instalada em um computador, os drivers associados deverão evitar tentar usar os mesmos contadores de hardware simultaneamente. Para evitar esses conflitos de recursos, todos os drivers que usam recursos de contador devem usar as rotinas HalAllocateHardwareCounters e HalFreeHardwareCounters para coordenar o compartilhamento desses recursos.

Um recurso de contador é um único contador de hardware, um bloco de contadores contíguos, uma interrupção de estouro de contador ou uma configuração de buffer de eventos em um PMU.

Antes de configurar os contadores, um driver pode chamar a rotina HalAllocateHardwareCounters para adquirir acesso exclusivo a um conjunto de recursos de contador. Depois que o driver não precisar mais desses recursos, ele deverá liberar os recursos chamando a rotina HalFreeHardwareCounters .

Em versões do Windows antes de Windows 10 versão 1903, uma chamada bem-sucedida para HalAllocateHardwareCounters concede ao chamador acesso exclusivo a todos os recursos de contador na unidade de monitor de desempenho de um sistema de processador único. Em um sistema multiprocessador, uma chamada bem-sucedida concede ao chamador acesso exclusivo a todos os recursos de contador em todos os processadores no sistema. GroupAffinity e ResourceList devem ser NULL e GroupCount deve ser zero.

A partir do Windows 10 versão 1903, os recursos de contador podem ser alocados com base na lista de recursos e nas afinidades de grupo fornecidas.

O software de virtualização normalmente não virtualiza contadores de desempenho de hardware. Portanto, esses contadores podem não estar disponíveis em uma máquina virtual, independentemente de HalAllocateHardwareCounters retornar um código status de STATUS_SUCCESS. Por exemplo, os contadores de desempenho de hardware não estão disponíveis em uma máquina virtual Hyper-V, mas HalAllocateHardwareCounters ainda pode retornar STATUS_SUCCESS.

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, Ntifs.h)
Biblioteca Hal.lib
DLL Hal.dll
IRQL PASSIVE_LEVEL

Confira também

GROUP_AFFINITY

HalFreeHardwareCounters

PHYSICAL_COUNTER_RESOURCE_LIST