Функция HalAllocateHardwareCounters (ntddk.h)
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 (include Ntddk.h, Ntifs.h) |
| библиотеки | Hal.lib |
| DLL | Hal.dll |
| IRQL | PASSIVE_LEVEL |