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 en todos los procesadores del sistema.
[in] GroupCount
Proporciona el número de estructuras de GROUP_AFFINITY proporcionadas por el parámetro groupAffintyGroupAffinityNULL.
[in] ResourceList
Puntero a un PHYSICAL_COUNTER_RESOURCE_LIST que contiene los recursos necesarios para el consumidor. Si este parámetro es NULL, el consumidor solicita la propiedad exclusiva de la unidad de supervisión del rendimiento.
[out] CounterSetHandle
Puntero a una ubicación en la que la rutina escribe un identificador en los recursos de contador asignados. 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. |
Observaciones
La mayoría de los procesadores tienen unidades de supervisión de rendimiento (PMU) que contienen una serie de contadores de hardware. Las herramientas de software usan estos contadores para supervisar varios 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 se instala más de una herramienta de este tipo 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 el HalAllocateHardwareCounters y HalFreeHardwareCounters rutinas 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 la versión 1903 de Windows 10, una llamada correcta a HalAllocateHardwareCounters concede al autor de la llamada acceso exclusivo a todos los recursos contadores de la unidad de monitor de rendimiento de un único sistema de procesador. En un sistema multiprocesador, una llamada correcta concede al autor de la llamada acceso exclusivo a todos los recursos contadores de todos los procesadores del sistema. GroupAffinity y ResourceList deben ser NULL y GroupCount debe ser cero.
A partir de la versión 1903 de Windows 10, 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 | Valor |
|---|---|
| cliente mínimo admitido | Disponible a partir de Windows 7. |
| de la plataforma de destino de | Universal |
| encabezado de | ntddk.h (incluya Ntddk.h, Ntifs.h) |
| biblioteca de | Hal.lib |
| DLL de | Hal.dll |
| irQL | PASSIVE_LEVEL |