Функция HalAllocateHardwareCounters (ntddk.h)

Статья
04/21/2023

Подпрограмма HalAllocateHardwareCounters выделяет набор ресурсов счетчика производительности оборудования.

Синтаксис

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

Параметры

GroupAffinty

Указатель на набор GROUP_AFFINITY структур, указывающих, какие ресурсы счетчика процессоров запрашивают потребитель. Если этот параметр имеет значение NULL, то запрос указывает выделение между всеми процессорами в системе.

[in] GroupCount

Предоставляет число GROUP_AFFINITY структур, предоставляемых параметром GroupAffinty , или ноль, если GroupAffinity имеет значение NULL.

[in] ResourceList

Указатель на PHYSICAL_COUNTER_RESOURCE_LIST , содержащий ресурсы, необходимые потребителю. Если этот параметр имеет значение NULL, потребитель запрашивает монопольное владение единицей мониторинга производительности.

[out] CounterSetHandle

Указатель на расположение, в которое подпрограмма записывает дескриптор в выделенные ресурсы счетчика. Чтобы освободить эти ресурсы позже, вызывающий объект должен передать этот дескриптор в подпрограмму HalFreeHardwareCounters . Если запрошенные ресурсы счетчика недоступны, HalAllocateHardwareCounters устанавливает значение *CounterSetHandle = NULL и возвращает STATUS_INSUFFICIENT_RESOURCES.

Возвращаемое значение

HalAllocateHardwareCounters возвращает STATUS_SUCCESS, если вызов был успешным. Возможные возвращаемые значения ошибок включают следующие коды состояния.

Код возврата	Описание
STATUS_INSUFFICIENT_RESOURCES	Запрошенные ресурсы счетчика в настоящее время недоступны.
STATUS_INVALID_PARAMETER	Вызывающий объект указал недопустимое значение параметра.
STATUS_NOT_SUPPORTED	Вызывающий объект предоставил ресурсы в списке ресурсов, которые в настоящее время не поддерживаются.

Большинство процессоров имеют единицы мониторинга производительности (PMU), которые содержат ряд аппаратных счетчиков. Программные средства используют эти счетчики для мониторинга различных аспектов производительности системы. Как правило, такое средство состоит из пользовательского драйвера в режиме ядра для программирования счетчиков и приложения пользовательского режима, которое взаимодействует с драйвером.

Если на компьютере установлено несколько таких средств, связанные драйверы не должны пытаться одновременно использовать одни и те же аппаратные счетчики. Чтобы избежать таких конфликтов ресурсов, все драйверы, использующие ресурсы счетчика, должны использовать процедуры HalAllocateHardwareCounters и HalFreeHardwareCounters для координации совместного использования этих ресурсов.

Ресурс счетчика — это один аппаратный счетчик, блок непрерывных счетчиков, прерывание переполнения счетчика или конфигурация буфера событий в PMU.

Перед настройкой счетчиков драйвер может вызвать подпрограмму HalAllocateHardwareCounters , чтобы получить монопольный доступ к набору ресурсов счетчиков. После того как драйверу больше не нужны эти ресурсы, он должен освободить ресурсы, вызвав подпрограмму HalFreeHardwareCounters .

В версиях Windows до Windows 10 версии 1903 успешный вызов HalAllocateHardwareCounters предоставляет вызывающей объекту монопольный доступ ко всем ресурсам счетчиков в единице монитора производительности однопроцессорной системы. В многопроцессорной системе успешный вызов предоставляет вызывающей объекту монопольный доступ ко всем ресурсам счетчика во всех процессорах в системе. GroupAffinity и ResourceList должны иметь значение NULL , а GroupCount — ноль.

Начиная с Windows 10 версии 1903 ресурсы счетчика можно выделять на основе списка ресурсов и сходства групп.

Программное обеспечение виртуализации обычно не виртуализирует аппаратные счетчики производительности. Таким образом, эти счетчики могут быть недоступны на виртуальной машине независимо от того, возвращает ли HalAllocateHardwareCounters код состояния STATUS_SUCCESS. Например, счетчики производительности оборудования недоступны на виртуальной машине Hyper-V, но HalAllocateHardwareCounters могут по-прежнему возвращать STATUS_SUCCESS.

Требования

Требование	Значение
Минимальная версия клиента	Доступно начиная с Windows 7.
Целевая платформа	Универсальное
Верхняя часть	ntddk.h (включая Ntddk.h, Ntifs.h)
Библиотека	Hal.lib
DLL	Hal.dll
IRQL	PASSIVE_LEVEL

См. также раздел

GROUP_AFFINITY

HalFreeHardwareCounters

PHYSICAL_COUNTER_RESOURCE_LIST