Función HalAllocateHardwareCounters (ntddk.h)
La rutina HalAllocateHardwareCounters asigna un conjunto de recursos de contador de rendimiento de hardware.
Sintaxis
NTHALAPI NTSTATUS HalAllocateHardwareCounters(
PGROUP_AFFINITY GroupAffinty,
[in] ULONG GroupCount,
[in] PPHYSICAL_COUNTER_RESOURCE_LIST ResourceList,
[out] PHANDLE CounterSetHandle
);
Parámetros
GroupAffinty
Puntero a un conjunto de estructuras de GROUP_AFFINITY que indican qué recursos de contador de procesadores solicita el consumidor. Si este parámetro es NULL, la solicitud indica una asignación entre todos los procesadores del sistema.
[in] GroupCount
Proporciona el número de estructuras de GROUP_AFFINITY proporcionadas por el parámetro GroupAffinty o cero si GroupAffinity es NULL.
[in] ResourceList
Puntero a un PHYSICAL_COUNTER_RESOURCE_LIST que contiene los recursos requeridos por el consumidor. Si este parámetro es NULL, el consumidor solicita la propiedad exclusiva de la unidad de supervisión de rendimiento.
[out] CounterSetHandle
Puntero a una ubicación en la que la rutina escribe un identificador en los recursos del contador asignado. Para liberar estos recursos más adelante, el autor de la llamada debe pasar este identificador a la rutina HalFreeHardwareCounters . Si los recursos de contador solicitados no están disponibles, HalAllocateHardwareCounters establece *CounterSetHandle = NULL y devuelve STATUS_INSUFFICIENT_RESOURCES.
Valor devuelto
HalAllocateHardwareCounters devuelve STATUS_SUCCESS si la llamada se realizó correctamente. Entre los posibles valores devueltos de error se incluyen los siguientes códigos de estado.
| Código devuelto | Descripción |
|---|---|
| STATUS_INSUFFICIENT_RESOURCES | Los recursos de contador solicitados no están disponibles actualmente. |
| STATUS_INVALID_PARAMETER | El autor de la llamada especificó un valor de parámetro no válido. |
| STATUS_NOT_SUPPORTED | El autor de la llamada proporcionó recursos en la lista de recursos que no se admiten actualmente. |
Comentarios
La mayoría de los procesadores tienen unidades de monitor de rendimiento (PMU) que contienen una serie de contadores de hardware. Las herramientas de software usan estos contadores para supervisar diversos aspectos del rendimiento del sistema. Normalmente, esta herramienta consta de un controlador en modo kernel personalizado para programar los contadores y una aplicación en modo de usuario que se comunica con el controlador.
Si hay más de una herramienta instalada en un equipo, los controladores asociados deben evitar intentar usar simultáneamente los mismos contadores de hardware. Para evitar estos conflictos de recursos, todos los controladores que usan recursos de contador deben usar las rutinas HalAllocateHardwareCounters y HalFreeHardwareCounters para coordinar su uso compartido de estos recursos.
Un recurso de contador es un único contador de hardware, un bloque de contadores contiguos, una interrupción de desbordamiento de contadores o una configuración de búfer de eventos en una PMU.
Antes de configurar los contadores, un controlador puede llamar a la rutina HalAllocateHardwareCounters para adquirir acceso exclusivo a un conjunto de recursos de contador. Después de que el controlador ya no necesite estos recursos, debe liberar los recursos llamando a la rutina HalFreeHardwareCounters .
En versiones de Windows anteriores a Windows 10 versión 1903, una llamada correcta a HalAllocateHardwareCounters concede al autor de la llamada acceso exclusivo a todos los recursos de contador de la unidad de monitor de rendimiento de un sistema de un solo procesador. En un sistema multiprocesador, una llamada correcta concede al autor de la llamada acceso exclusivo a todos los recursos de contador de todos los procesadores del sistema. GroupAffinity y ResourceList deben ser NULL y GroupCount debe ser cero.
A partir de Windows 10 versión 1903, los recursos de contador se pueden asignar en función de la lista de recursos y las afinidades de grupo proporcionadas.
Normalmente, el software de virtualización no virtualiza los contadores de rendimiento de hardware. Por lo tanto, es posible que estos contadores no estén disponibles en una máquina virtual, independientemente de si HalAllocateHardwareCounters devuelve un código de estado de STATUS_SUCCESS. Por ejemplo, los contadores de rendimiento de hardware no están disponibles en una máquina virtual de Hyper-V, pero HalAllocateHardwareCounters podría seguir devolviendo STATUS_SUCCESS.
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Disponible a partir de Windows 7. |
| Plataforma de destino | Universal |
| Encabezado | ntddk.h (include Ntddk.h, Ntifs.h) |
| Library | Hal.lib |
| Archivo DLL | Hal.dll |
| IRQL | PASSIVE_LEVEL |